本blog用于归档如何在GitHub搭建个人博客的过程,内容参考来自本篇文章《如何用 GitHub 从零开始搭建一个博客》 以及hexo中文官网的文档。
更新:这篇文章写于今年年初,个人博客在年初已使用GitHub Pages搭建开源博客主页,今年下半年GitHub Pages在国内出现了某一时期无法正常访问,因此将其切换到国内Gitee Pages以保证主页正常访问,确实也需支持国内开源平台。
前言
选用GitHub/Gitee发布开源博客的理由
个人就使用CSDN相关看法:
- 优势:
首先CSDN流量不愁,不同博主之间可以进行留言、私信等方式进行技术交流等,其次CSDN提供不错Markdown编辑器工具,例如在线草稿、离线草稿、图片拖曳与上传、定时保存等功能相对完善。 - 不足:
发布文章后,博客页面两栏窗口过多广告,对于推崇简洁主义的开发者来说(尤其已经习惯MacOS暗黑模式高度focus的UI)较为烦人,毕竟CSDN平台运营存在大量的商业行为。
而GitHub/Gitee搭建的博客为开源博客,以静态文件方式发布,通过整合一些博客框架提供的简洁模板,可以为技术文章撰写者和阅读者提供“无打扰”的简约而清爽的阅读环境。
GitHub/Gitee可构建个人开源博客主页
GitHub/Gitee上除了最重要的代码仓库功能,还有GitHub Pages (国内为Gitee Pages)功能,可用于部署静态网页文件,只要发布者整合基本的工具,通过博客框架将本地Markdown文件编译为静态网页文件,再部署到GitHub/Gitee仓库,访问URL即可看到该静态网页。因此技术撰写者需要做的事情为:
- 配置GitHub /GitHub Pages 本地博客开发环境
- 在本地完成Markdown文章
- push 到GitHub/Gitee完成公网的博客发布
目前GitHub Pages在国内已无法正常访问(VPN除外),因此开源博客主页在个人的Gitee仓库部署。
Gitee pages相关环境配置
新建一个Repository用于存博客文件
首先在个人Gitee 新建一个仓库,名称为blog,当然gitee开启pages功能后,主页url会被gitee自动设为
https://yield-bytes.gitee.io/blog
需注意:若基于GitHub Pages 部署博客,需要按以下规则建立仓库名称:
名称为 {yourblogname}.github.io,仓库名称必须以github.io 为后缀结尾,国内的gitee不需要此方式。
本地git的配置
1 | git config --global user.name "用户名" |
配置码云 ssh key
1 | ssh-keygen -t rsa -C '注册码云的邮箱' |
其中-t指定密钥类型,这里设置rsa即可,-C是密钥的注释,这里设置成邮箱方便分辨
将公钥打印出来
1 | cat ~/.ssh/id_rsa.pub |
在码云上添加ssh 公钥:在个人设置里面找到相应的ssh key添加界面处理即可
测试连接是否成功
1 | **** % ssh gitee@gitee.com |
测试往仓库推一个新建文件
1 | mkdir MyTecBlog |
在web端的gitee仓库可看到README.md文件以及提交记录
Hexo环境配置
Hexo依赖node.js,借用相关npm包,使得搭建出来的GitHub博客不会过于简单。
MacOS直接用brew安装即可:
1 | brew install node |
安装 Hexo博客框架
借助Hexo博客框架,可以快速部署和设计博客,Hexo自带命令行命令。
1 | #拉取源设置为淘宝镜像 |
在macOS安装 hexo-cli可能会提示未安装xcode CommandLineTools
xcode-select --print-path
查看 command-line tools 的安装路径,不出意外显示的结果应该是/Library/Developer/CommandLineTools
sudo rm -r -f /Library/Developer/CommandLineTools,
卸载 command-line toolsxcode-select --install,重新安装
command-line tools
创建hexo博客项目
创建一个名为yield-bytes的博客项目(名字可以任意取)1
2
3
4
5yymac@wonder hexo init yield-bytes
yymac@wonder yield-bytes % ls
_config.yml package.json themes
node_modules scaffolds
package-lock.json source
可以看到yield-bytes为一个目录,该目录下有相应的node模块目录、配置文件、主题目录等。
将项目编译成静态文件
1 | yymac@wonder yield-bytes % hexo generate |
项目目录下多了一个public目录,可以看到这些就是静态网页内容:css、html、js等1
2
3yymac@wonder public % ls
2020 css index.html
archives fancybox js
其中index.html就是hexo的demo博客展示页面,通过在public目录下运行hexo server
将页面作为web服务跑起来1
2
3yymac@wonder public % hexo server
INFO Start processing
INFO Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.
在浏览器可以看到hexo的demo博客主页
将本地demo博客部署到gitee
只需要在hexo创建的项目目录下的_config.yml
加入gitee.io仓库的相关配置,hexo可一键部署到gitee上。
1 | npm install hexo-deployer-git --save |
修改_config.yml
,需要修改两处地方1
2
3
4
5
6
7
8
9
10
11
12# URL
# If your site is put in a subdirectory, set url as 'http://example.com/child' and root as '/child/'
url: https://yield-bytes.gitee.io/blog
root: /blog/
# Deployment
# Docs: https://hexo.io/docs/one-command-deployment
deploy:
type: git
repo: git@gitee.com:yield-bytes/blog.git
branch: master
上述提示本地静态网页文件已经push到gitee的blog仓库
打开网址https://yield-bytes.gitee.io/blog
,即可看到demo主页
配置和完善个人博客
前面章节仅完成基本的搭建,从本章开始,将完善个人博客的配置以及UI。在_config.yml
文件里面,分了很多部分,都可用于配置博客不同功能
修改博客简介等基本内容:
1 | 4 # Site |
本地运行刷新即可看到主页修改后的效果。
为博客设置主题
博客当然可以设置为不同风格的UI,称为主题,在前十年那会,网易163博客还很流行,博客主可根据平台提供不同模板将自己的博客打造更加高级,有些模板还需要VIP或者付费。在当今开源时代,Hexo提供很多不错的博客模板,网址:https://hexo.io/themes/
,可直接clone使用,以next主题为例子的配置过程:
在yield-bytes/themes
目录下仅有一个默认的landscape主题
1 | yymac@wonder themes % ls |
将next主题拉到该目录下1
2
3yymac@wonder themes % ls
yymac@wonder themes % git clone https://github.com/theme-next/hexo-theme-next
hexo-theme-next landscape
在yield-bytes根目录下修改_config.yml 文件,在 theme 配置部分,修改为 hexo-theme-next:1
2
3
44 # Extensions
3 ## Plugins: https://hexo.io/plugins/
2 ## Themes: https://hexo.io/themes/ # 官方提供更多开源的主题以及插件
1 theme: hexo-theme-next # 更换主题
重启hexo server即可看到主页已经换成next主题
对主题进行深度定制
- 更换样式
每个主题的目录下也有一个_config.yml
博客样式配置文件,这里可进行深度定制1
2
3
4yymac@wonder hexo-theme-next % ls
LICENSE.md crowdin.yml languages scripts
README.md docs layout source
_config.yml gulpfile.js package.json
next 默认有四个样式,这里设为Pisces样式,也可打开暗黑模式1
2
3
4
5
6
7
8# Schemes
#scheme: Muse
#scheme: Mist
scheme: Pisces
#scheme: Gemini
# Dark Mode
darkmode: true
- 更换title的logo
由于logo需要出裁剪为一定尺寸的png图片,需自行设计。在next主题下的_config.yml
的favicon部分可进行更换logo的配置。1
2
3
4
5favicon:
small: /images/favicon-16x16-next.png
medium: /images/favicon-32x32-next.png
apple_touch_icon: /images/apple-touch-icon-next.png
safari_pinned_tab: /images/logo.svg
- avatar 设置头像后者主页的标识图像
只需将图片放在该路径:themes/hexo-theme-next/source/images 路径,在next主题下的_config.yml
文件下配置为该图片路径,也可设为网络图片路径
1 | 7 avatar: |
为个人博客开启RSS(用处不大)
在hexo创建的博客项目目录下安装feed插件,博客项目安装的所有插件都放置在node_modules目录下1
yymac@wonder yield-bytes % npm install hexo-generator-feed --save
安装完成之后不需要其他的配置,以后每次编译生成站点的时候就会自动生成 RSS Feed 文件
修改code代码的显示样式
在文章中,经常需要贴上代码,为保证阅读效果,可将默认浅灰色样式设为Mac样式,看起还不错。1
2
3
4
5
6
7
8
9
10
11
1212 codeblock:
11 # Code Highlight theme
10 # Available values: normal | night | night eighties | night blue | night bright | solarized | solarized dark | galactic
9 # See: https://github.com/chriskempson/tomorrow-theme
8 highlight_theme: solarized dark
7 # Add copy button on codeblock
6 copy_button:
5 enable: true
4 # Show text copy result.
3 show_result: true
2 # Available values: default | flat | mac
1 style: mac
default样式:
mac样式:
- back2top设置页面滚动逻辑、阅读进度
1 | 14 back2top: |
打开Bookmark Support功能后,可以提示阅读体验,例如关闭该文章后,再打开浏览,可以恢复到上次阅读位置,类似微信阅读文章的体验。
- 为每篇文章关联GitHub Banner
大家阅读一些技术文章应该经常看到文章右上角有GitHub的图标,该链接就是去GitHub Repository:1
2
3
4
5 4 # `Follow me on GitHub` banner in the top-right corner.
3 github_banner:
2 enable: true
1 permalink: https://github.com/yield-bytes/yield-bytes.github.io
403 title: Follow me on GitHub
- 为博客正确显示math 的Markdown语法
为了能让文章中能正常显示数学公式(常见数据挖掘、深度学习等文章),可通过hexo为next主题引入相关插件。1
yymac@wonder yield-bytes % npm install hexo-renderer-kramed --save
注意:这里不要安装hexo-renderer-pandoc,该库的js有bug,无法正确解析Markdown文章,会导致hexo运行报错
在主题配置打开math配置即可:
1 | 1 math: |
- 开启无刷新加载页面
为进一步提升博客体验,hexo支持页面实现无刷新加载,借助pjax插件即可。
首先在配置文件里开启pjax
1 | 1 # pjax: //cdn.jsdelivr.net/gh/theme-next/theme-next-pjax@0/pjax.min.js |
在hexo-theme-next目录下,安装该插件1
2
3yymac@wonder hexo-theme-next % pwd
***/yield-bytes/themes/hexo-theme-next
yymac@wonder hexo-theme-next % git clone https://github.com/theme-next/theme-next-pjax source/lib/pjax
到处,已经完成对搭建博客的较为深度的定制,其他定制可参考官网:https://theme-next.org/docs/getting-started/,这里不再累赘。
文章设置
前置章节主要对博客主题及其UI做定制配置,本章节介绍如何在搭建的Gitee Pages上发布新文章等内容。
增加文章
新增一篇名为《深入理解异步IO的底层逻辑——IO多路复用(select、poll、epoll)》的文章
在本地yield-bytes根目录创建文章,文章类型为Markdown格式
1 | yymac@wonder yield-bytes % hexo new 深入理解异步IO的底层逻辑——IO多路复 用(select、poll、epoll) |
所有新建的文章的都拷贝到该目录下1
2
3
4yymac@wonder yield-bytes % cd source/_posts/
yymac@wonder _posts % ls
hello-world.md
深入理解异步IO的底层逻辑——IO多路复用(select、poll、epoll).md
每篇文章的头部为该文章的元数据,例如标题,创建时间,标签,文章分类,有关文章属性更为详细的配置,可以参考:https://hexo.io/zh-cn/docs/writing.html1
2
3
4
5
6
7
8
9 ---
title: 深入理解异步IO的底层逻辑——IO多路复用(select、poll、epoll)
date: 2020-02-01 21:50:46
tags:
- IO多路复用
- epoll
categories:
- Python进阶
---
头部元数据之后就是Markdown的正文
修改文章字体
在next主题的配置文件_config.yml
里面,font 部分可以设置文章显示字体,默认博客站点的字体大小为1,个人在global设为0.8后,文字看起相对舒服1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
1616 font:
15 enable: true
14
13 # Uri of fonts host, e.g. //fonts.googleapis.com (Default).
12 host:
11
10 # Font options:
9 # `external: true` will load this font family from `host` above.
8 # `family: Times New Roman`. Without any quotes.
7 # `size: x.x`. Use `em` as unit. Default: 1 (16px)
6
5 # Global font settings used for all elements inside <body>.
4 global:
3 external: true
2 family: Lato
1 size: 0.8
为博客左侧增加标签页、分类页等链接
上面搭建的博客仅有少量栏目例如文章栏目、主页栏目,每次发布文章前,我们需要为其打个标签,以便当文章数量较多时,读者可在标签页查看相关的标签,从而快速找到相关文章,例如一篇streaming和kafka整合的文章,标签可以打为:streaming、kafka、实时流计算等。此外还需多文章进行分类,例如Python进阶分类、spark相关的分类、数据分析与挖掘的分类、数据结构与算法的分类、Linux相关的分类等
创建标签页和分类页:
1 | yymac@wonder yield-bytes % hexo new page tags |
创建的标签页以及分类页都是Markdown文件
标签页的md:1
2
3
4
51 ---
1 title: tags
2 date: **** 10:58:03
3 ---
~
分类页的md:1
2
3
41 ---
1 title: categories
2 date: *** 11:32:51
3 ---
将tags的md指定为标签页:1
2
3
4
5
61 ---
1 title: tags
2 date: *** 10:58:03
3 type: tags
4 comments: false # 这里表示关闭当前文章的评论
5 ---
将categories制定为分类页:1
2
3
4
5
61 ---
1 title: categories
2 date: *** 11:32:51
3 type: categories
4 comments: false
5 ---
在next主题的配置文章的menu部分新增tags访问路径和categories访问路径,这里就是配置页面路由的地方,可自行新增路径。
配置说明:tags: /tags/ || fa fa-tags
表示tags的路径为/tags/,对应的icon图标为fa fa-tags
这里有一个图标与名称对应的地址:https://v3.bootcss.com/components/#glyphicons
,将选中的icon图标名称如glyphicons glyphicons-th-large改为fa fa-th-large即可
1 | menu: |
刷新后访问http://localhost:4000/tags/
即可
若需要对文章添加多个分类,用以下格式书写:
1 |
|
再增加一个404页面:
1 | hexo new 404 |
在yield-bytes/source/404/路径下,更改index.md内容
1 | --- |
博客左侧menu菜单显示图片
在next主题的配置文件_config.yml下加入Avatar地址即可
1 | # Sidebar Avatar |
多篇文章在首页的展示逻辑
若博客已发布多篇文章,next主题默认在首页里将在可视化区域窗口内展示所有文章的所有完整内容,而不是只显示每篇文章的摘要部分,这将导致无法预览多篇文章内容。处理方式很简单,hexo支持对每篇文章提供只显示摘要部分,文章的更多内容则用more提示来指引读者。
处理方式:
在每篇Markdown文章比较靠前的位置,加入<!--more-->
标识即可,例如下面的两篇文章:
第一篇文章,在首页中,只给它显示前言的内容即可
第二篇spark streaming的文章,在首页,将该文的第1章节前面几句作为文章摘要显示
最后在查看首尔显示效果:
可以看到首页的多篇文章只展示<!--more-->
前面的内容。
为博客增加全站搜索功能
开启博客全文搜索功能需要加入相关插件1
yymac@wonder yield-bytes % npm install hexo-generator-searchdb --save
首先在yield-bytes项目的_config.yml
新增搜索配置:1
2
3
4
5
61
2 search:
3 path: search.xml
4 field: post
5 format: html
6 limit: 1000
再到next主题的_config.yml
开启相关检索配置,这里启动 Local Search功能,这里的配置也提示了需要安装依赖hexo-generator-searchdb插件:1
2
3
4
5
6
7
8
9
10
11
12
13
14 8 # Local Search
7 # Dependencies: https://github.com/theme-next/hexo-generator-searchdb
6 local_search:
5 enable: true
4 # If auto, trigger search by changing input.
3 # If manual, trigger search by pressing enter key or search button.
2 trigger: auto
1 # Show top n results per article, show all results by setting to -1
761 top_n_per_article: 5
1 # Unescape html strings to the readable one.
2 unescape: false
3 # Preload the search data when the page loads.
4 preload: false
5
上述表示输入关键字后自动触发搜索,并只显示5条命中记录。从效果来看,不得不佩服hexo博客框架(结合各类第三方插件)确实强大。(在独立开发的博客项目中,若要启用全文检索,则需引入elasticsearch技术栈)
至此,博客的文章板块已经定制完毕,重新编译部署到gitee即可看到效果
为GitHub Pages配置自定义域名(注意以下不是Gitee Pages的配置)
GitHub pages为git用户提供免费的自定义域名服务,所搭建的博客站点可无需使用类似https://yourrepo.github.io
作为访问地址
在github博客项目仓库的Settings里面的GitHub Pages 可进行自定义域名设置:
为文章添加字数统计和阅读时长
1 | post_wordcount: |
安装相关插件
1 | yymac@wonder yield-bytes % $ npm install eslint --save |
在博客yield-bytes项目根目录的_config.yml文件的最后加入以下配置1
2
3
4
5
6symbols_count_time:
symbols: true # 文章字数统计
time: true # 文章阅读时长
total_symbols: true # 站点总字数统计
total_time: true # 站点总阅读时长
exclude_codeblock: false # 排除代码字数统计
在next主题的配置文件已有相关文章计数配置1
2
3
4symbols_count_time:
separated_meta: true # 是否另起一行(true的话不和发表时间等同一行)
item_text_post: true # 首页文章统计数量前是否显示文字描述(本文字数、阅读时长)
item_text_total: false # 页面底部统计数量前是否显示文字描述(站点总字数、站点阅读时长)
注意字体统计效果需重新hexo clean 和hexo generate才有效果,直接重启本地hexo server将无效
最后重新部署一遍博客即可:
1 | hexo clean |
自动更新Gitee Pages
GitHub Pages只要 push上去,主页文章就会自动更新,但Gitee Pages的个人版无法实现自动更新,需要手动在仓库设置中点击更新按钮,若想自动化该过程,可以用selenium爬虫工具实现,npm有一个插件可以实现该过程——官网地址
当然使用Python也可以快速开发一个自动更新脚本
本地git同时配置github和gitee(重要)
由于在开发项目或者博客项目中,若只设置的github 公钥或者gitee的公钥,那么git push到仓库只能二选一,下面给出同一台电脑同时配置github和gitee
为github生成对应的公钥
1 | ssh-keygen -t rsa -f ~/.ssh/id_rsa.github -C "****@qq.com" # 备注用,可以用github注册邮箱或自定义 |
为gitee生成对应的公钥
1 | ssh-keygen -t rsa -f ~/.ssh/id_rsa.gitee -C "****@qq.com" # 备注用,可以用gitee注册邮箱或自定义 |
因bash shell执行 ssh时默认读取id_rsa为名称的公钥,为了让ssh访问github.com和gitee.com时使用对应的id_rsa.github和id_rsa.gitee ,需将这两个公钥加入到 本地ssh agent 中:
1 | ***@MacBookPro .ssh % ssh-agent bash |
在~/.ssh目录下创建一个config文件,无需后缀,其实就是告诉ssh -T 域名
命令运行时路由到对应的公钥
1 | ***@MacBookPro .ssh % vi config |
文件内容:
1 | Host github.com |
最后分别将~/.ssh目录下的id_rsa.github.pub以及id_rsa.gitee.pub里面的公钥复制到平台ssh key设置,本地再测试是否通过:
1 | ***@MacBookPro ~ % ssh -T git@github.com |