本文最初发布于我的个人博客Bambrow's Blog,采用 BY-NC-SA 许可协议,转载请注明出处。若有后续更新,将更新于原博客。欢迎去我的博客阅读更多文章!
本文详细记录一下站点建立过程,以便查阅。对于具体的细节则不会做过多解释,主要展示步骤。这一篇主要讲述准备工作、首次部署与自动部署的相关内容。
本文运行环境:
node: v14.4.0
npm: 6.14.7
hexo: 4.2.1
hexo-cli: 3.1.0
准备工作
准备工作主要参考了Hexo官方文档。
安装Git与Node.js
在Mac上最方便的方法当然是通过Homebrew。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
注意,可能在安装之前需要先安装Command Line Tools for Xcode。直接在终端输入xcode-select --install
安装。
安装好Homebrew后,直接使用以下命令:
brew install git
brew install node
在安装以上两个依赖之前,可以先运行brew update
来更新Homebrew。此外,还可以运行brew doctor
检查一下有没有什么冲突,可以及时处理。也可以把以下语句加入你的.bash_profile
或者.zshrc
,取决于你使用的shell:
export PATH="/usr/local/bin:$PATH"
安装好后,可以用以下命令查看是否安装成功,成功则会返回版本号:
git --version
npm -v
安装Hexo
直接使用npm
安装:
npm install -g hexo-cli
查看一下hexo
是否安装成功,会返回当前的hexo
版本号:
hexo -v
注册GitHub并新建个人仓库
GitHub就不用多说了。注册完成后,新建公有仓库,名称为你的GitHub用户名.github.io
。这个仓库用来存放渲染好的页面。
此外,我们再新建一个私有仓库,用来存放源文件本身。仓库的名字任意取,我取的名字是blog
。
这两个仓库最好不要初始化任何东西,也就是README
,.gitignore
和license
都不要。这样新建的仓库完全是空的。
设置Git与密钥文件
首先运行以下两句进行Git配置:
git config --global user.name "GitHub用户名"
git config --global user.email "GitHub注册邮箱"
其中把用户名和邮箱替换成你自己的。然后我们生成密钥文件:
ssh-keygen -t rsa -C "GitHub注册邮箱"
直接一路回车下去就好,结束后会在~/.ssh/
文件夹里生成id_rsa
私钥文件与id_rsa.pub
公钥文件。我们读取一下公钥的内容并且手动拷贝:
cat ~/.ssh/id_rsa.pub
手动复制显示的内容。随后打开这个页面设置SSH Key。你也可以在GitHub主页点击你的右上角头像,选择Settings,然后选择SSH and GPG Keys找到这个界面。点击New SSH Key,标题可以随便写,内容就是你刚才复制的公钥内容,随后保存。
开始建站
博客初始化
首先选择一个你喜欢的地方作为你的博客根目录。
mkdir ~/git/你的GitHub用户名.github.io
随后按照官方教程,依次运行:
hexo init ~/git/你的GitHub用户名.github.io
cd ~/git/你的GitHub用户名.github.io
npm install
现在博客已经初始化完成了。使用以下命令:
hexo server
就可以在http://localhost:4000看到你的站点了。可以在终端里使用control+c
关掉本地服务器。下面列举一些常用的命令,更多命令与参数可以参考这里:
-
hexo clean
用于清除缓存与静态文件。 -
hexo new "文章标题"
用于新建文章。 -
hexo server
用于启动本地服务器查看渲染好的网页,可简写为hexo s
。 -
hexo generate
用于生成静态文件,可简写为hexo g
。 -
hexo deploy
用于部署网站,需要先设置好_config.yml
,可简写为hexo d
。
设置_config.yml
首先,可以参考官方的设置页面,这里只涉及一些核心设置。
用你喜欢的编辑器打开根目录下的_config.yml
(注意不是themes
文件夹里面的_config.yml
)。
在Site
下面你可以更改网页的标题、副标题、描述、作者、语言、时区等等。语言这里选择zh-CN
。在URL
下面可以把url
改为你的GitHub Pages的URL,https://你的GitHub用户名.github.io
。中间的大部分设置跳过,你也可以参照上面的网页进行修改。
最后,我们重点关注一下# Deployment
。在这里,我们需要把它改为如下的样式:
deploy:
type: git
repo: 你的GitHub目录地址
branch: master
其中repo
要根据自己的情况修改。你可以在GitHub主页点击你的头像,选择Your repositories,点击你的你的GitHub用户名.github.io
仓库,点击Code按钮,然后点击Use SSH(如果目前显示为Clone with HTTPS),然后复制框中的内容到这里。
修改好后,保存文件。
首次部署
我们需要再安装一个依赖:
npm install hexo-deployer-git --save
随后一切就绪,依次运行:
hexo clean
hexo g
hexo d
然后你就可以在https://你的GitHub用户名.github.io
看到渲染好的网页了。
设置自动部署
在这一步里我们不仅备份了博客的源文件,也实现了修改push到blog
私有仓库后触发GitHub Actions完成自动部署。
将源文件备份至私有仓库
在终端,自己的GitHub用户名.github.io
文件夹内,手动添加远程仓库:
git init
git remote add origin [email protected]:bambrow/blog.git
这里的远程仓库就是你的blog
仓库。把上面的[email protected]:bambrow/blog.git
修改成你自己的仓库地址。方法同样是在网页进入blog
仓库,点击Code按钮,然后点击Use SSH(如果目前显示为Clone with HTTPS),然后复制框中的内容到这里。
随后我们编辑一下.gitignore
文件。可以使用你喜欢的编辑器。一般来讲,.gitignore
应该有如下内容:
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
编辑好之后,先做:
git pull origin master
随后把所有应该备份的文件push到GitHub:
git add .
git commit -m "initial commit"
git push origin master
此时去GitHub上查看blog
仓库,会发现内容已经更新。
设置GitHub Actions
请注意,在做这一步之前,请务必确认自己的blog
仓库是私有仓库,如果不是,一定要在设置里将其设置为私有。
之前建立好的密钥文件,有公钥也有私钥。我们已经用过了公钥,这次使用私钥。首先读取其内容并手动拷贝:
cat ~/.ssh/id_rsa
手动复制全部内容。随后在网页上打开自己的blog
仓库,点击Settings,再点击左侧的Secrets,随后新建。名称可以随意写,这里推荐HEXO_DEPLOY_KEY
;内容则是刚才复制的私钥全部内容。随后点击添加。
随后,我们开始设置工作流。点击你的仓库标签下的Actions,选择新建New workflow。随后选择set up a workflow yourself,将main.yml
的内容替换如下,你也可以自行修改:
# 工作流名称
name: Hexo Blog Deploy
# 只在push到master分支的时候启动
on:
push:
branches:
- master
# 使用ubuntu虚拟机
jobs:
build:
runs-on: ubuntu-latest
# 工作流步骤
steps:
- name: Checkout repository master branch
uses: actions/checkout@master
with:
submodules: true
# 安装Node.js
- name: Install node.js
uses: actions/setup-node@master
with:
node-version: "10.x"
# 安装Hexo
- name: Install hexo
run: |
npm install hexo-cli -g
npm install
# 设置SSH密钥,读取HEXO_DEPLOY_KEY
- name: Setup private key
env:
HEXO_DEPLOY_KEY: ${{ secrets.HEXO_DEPLOY_KEY }}
run: |
mkdir -p ~/.ssh/
echo "$HEXO_DEPLOY_KEY" > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
ssh-keyscan github.com >> ~/.ssh/known_hosts
# 配置Git设置
- name: Setup git settings
run: |
git config --global user.name "GitHub用户名"
git config --global user.email "GitHub邮箱"
# 更改上面的用户名和邮箱
# 部署
- name: Deploy hexo
run: |
hexo clean
hexo generate
hexo deploy
随后点击Start commit结束设置。这样以后只要有新的改动被push到blog
的主分支,就后触发这个工作流,将网页渲染出来,同时也会push到你的GitHub用户名.github.io
这个仓库里。
安装Markdown语法扩展
Hexo
原生的Markdown渲染插件支持的Markdown语法不够丰富,比如不支持GitHub Flavored Markdown、CommonMark、上标下标、脚注等等。因此,我们在写文章之前,可以把原生的插件hexo-renderer-marked
改为hexo-renderer-markdown-it
。
首先,根据该插件的安装指南,运行以下命令:
npm uninstall hexo-renderer-marked
npm install hexo-renderer-markdown-it
随后在_config.yml
里添加如下语句(可以添加在deploy
前面):
# Markdown-it config
## Docs: https://github.com/celsomiranda/hexo-renderer-markdown-it/wiki
markdown:
render:
html: true
xhtmlOut: false
breaks: true
linkify: true
typographer: true
quotes: '“”‘’'
plugins:
- markdown-it-abbr
- markdown-it-footnote
- markdown-it-ins
- markdown-it-sub
- markdown-it-sup
anchors:
level: 2
collisionSuffix: 'v'
permalink: true
permalinkClass: header-anchor
permalinkSide: 'left'
permalinkSymbol: ¶
随后你就可以使用扩展语法了。使用方法可以参看这里和这里,尤其是后一个网页给出了很详细的例子。
如果你觉得脚注字体偏大,可以看我的字体设置文章,看完后就知道怎么修改了。我个人做了如下设置:
.footnotes {
font-size: 75%;
}
因为我们引入了新的插件,所以也要改一下工作流文件,在安装Hexo
那一步加一些步骤,安装这些依赖。你可以在本地修改.github/workflows/main.yml
的内容,也可以在GitHub的blog
仓库,点击Actions,选择最近的一次部署,点击右侧的省略号中的View workflow file,然后点击右侧的铅笔按钮进行修改。将新的依赖安装写在npm install
那一行后面即可。如果你采用后者,在你将本地新的改动push到GitHub之前,要记得先做git pull
,否则会报错显示远程仓库有新的改动。推荐在本地修改,一步到位。
run: |
npm install hexo-cli -g
npm install
+ npm uninstall hexo-renderer-marked
+ npm install hexo-renderer-markdown-it