文章
26
标签
29
分类
10
主页
归档
标签
分类
友链
关于
兴趣
目录
  1. 1. 前言
  2. 2. 准备环境
  3. 3. 安装Hexo
  4. 4. 部署Github Pages
    1. 4.1. 新建仓库
    2. 4.2. 配置SSH
    3. 4.3. 部署Hexo
    4. 4.4. 写作
    5. 4.5. 绑定域名
    6. 4.6. Hexo升级
  5. 5. Github Actions自动部署
    1. 5.1. 准备工作
    2. 5.2. 触发条件和运行环境
    3. 5.3. 建立工作环境
    4. 5.4. 生成部署文件
    5. 5.5. 部署博客
    6. 5.6. 完整配置文件
  6. 6. Hexo配置
    1. 6.1. 标签外挂
      1. 6.1.1. note提示块
      2. 6.1.2. tabs标签卡
      3. 6.1.3. button按钮
  7. 7. 参考
Kylen's Blog
主页
归档
标签
分类
友链
关于
兴趣
Hexo+Github Pages搭建博客攻略
|软件
字数总计: 4.3k|阅读时长: 17 分钟|阅读量:

前言

博客有第三方平台，也可以自建，比较早的有博客园、CSDN，近几年新兴的也比较多诸如：WordPress、segmentFault、简书、掘金、知乎专栏、Github Page、Coding Pages、Gitee等等。

这次我要说的就是 Github Page + Hexo 搭建个人博客的方式！Github Page 是 Github 提供的一种免费的静态网页托管服务（免费空间有限制，但是足够用了），可以用来托管博客、项目官网等静态网页。支持 Jekyll、Hugo、Hexo 编译静态资源，这次我们的主角就是 Hexo 了，具体的内容下面在文章内介绍。

准备环境

准备 node 和 git 环境。 Hexo 是基于 Node.js 驱动的一款博客框架，首先安装 Node.js，简单的说 Node.js 就是运行在服务端的 JavaScript。然后安装Git，Git是一个分布式版本控制系统，用于项目的版本控制管理，作者是 Linux 之父。

两个工具不同的平台安装方法有所不一样，可自行了解按步骤安装，这里不详述了。安装成功后打开git bash（Windows）或者终端（Mac），下方中将统一称为命令行。在命令行中输入相应命令验证是否成功，如果成功会有相应的版本号。

1
2
3
git version
node -v
npm -v

安装Hexo

如果以上环境准备好了就可以使用 npm 开始安装 Hexo 了。也可查看 Hexo 的详细文档。在命令行输入执行以下命令：

1
npm install -g hexo-cli

安装 Hexo 完成后，再执行下列命令，Hexo 将会在指定文件夹中新建所需要的文件。

1
2
3
hexo init myBlog
cd myBlog
npm install

新建完成后，指定文件夹的目录如下：

1
2
3
4
5
6
7
8
.
├── config.yml # 网站的配置信息，您可以在此配置大部分的参数。
├── package.json
├── scaffolds # 模版文件夹
├── source  # 资源文件夹，除 _posts 文件，其他以下划线开头的文件或者文件夹不会被编译打包到public文件夹
|   ├── _drafts # 草稿文件
|   └── _posts # 文章Markdowm文件
└── themes  # 主题文件夹

好了，如果上面的命令都没报错的话，就恭喜了，运行 hexo s 命令，其中 s 是 server 的缩写，在浏览器中输入 http://localhost:4000 回车就可以预览效果了。

部署Github Pages

新建仓库

首先如果你还没有 Github 账号的先注册一个，注册过程略。

Github上 new repository 创建新仓库。Github 仅能使用一个同名仓库的代码托管一个静态站点，仓库名称必须是用户名.github.io。打开仓库创建一个 index.html 文件，并随意先写点内容，比如 Hello World， 打开 http://你的用户名.github.io 站点，可看到预览效果。

配置SSH

要使用 git 工具首先要配置一下SSH key，为部署本地博客到 Github 做准备。

打开命令行输入 cd ~/.ssh 如果没报错或者提示什么的说明就是以前生成过的，直接使用 cat ~/.ssh/id_rsa.pub 命令就是可以查看本机上的 SSH key 了。

1
cat ~/.ssh/id_rsa.pub

如果之前没有创建，则执行以下命令全局配置一下本地账户：

1
2
git config --global user.name "用户名"
git config --global user.email "邮箱地址"

然后开始生成密钥 SSH key

1
ssh-keygen -t rsa -C '上面的邮箱'

按照提示回车，即可生成 ssh key。通过查看 ~/.ssh/id_rsa.pub 文件内容，获取到你的 SSH key。首次使用还需要确认并添加主机到本机SSH可信列表。若返回 Hi xxx! You've successfully authenticated, but GitHub does not provide shell access. 内容，则证明添加成功。

1
ssh -T git@github.com

到这还没完，还要登录 Github 上添加刚刚生成的 SSH key。 创建一个新的 SSH key, 标题随便，key 就填刚才生成那个，确认创建，搞定！！这样在你的 SSH keys 列表里就会看到你刚刚添加的密钥。

部署Hexo

此时，本地和 Github 的工作做得差不了，是时候把它们两个连接起来了。你也可以查看官网的部署教程。先不着急，部署之前还需要修改配置和安装部署插件。
第一：打开项目根目录下的 _config.yml 配置文件配置参数。

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git
  repo: git@github.com:XXX/XXX.github.io.git #github仓库地址
  branch: master # github分支

同时部署到多个仓库

1
2
3
4
5
deploy:
  type: git
  repo:
     github: git@github.com:XXX/XXX.github.io.git,master
     gitee: git@gitee.com:XXX/XXX.git,master

第二：要安装一个部署插件 hexo-deployer-git。

1
npm install hexo-deployer-git --save

最后执行以下命令就可以部署上传啦，以下 g 是 generate 缩写，d 是 deploy 缩写：

1
hexo g -d

hexo generate，生成的静态内容在 public 文件夹内。hexo clean，执行此操作会删除 public 文件夹中的内容。 hexo 命令组合

1
2
hexo clean && hexo g -s，就是清除、生成、启动
hexo clean && hexo g -d，就是清除、生成、部署

写作

博客搭好了，就开始写文章了，这里简单介绍一下，详细的文档可以看 hexo 官网。新建文章，输入以下命令即可

1
hexo new <title>

此时在source_posts文件夹中便会多出一个文档 “title.md“。如果要删除，直接在此文件夹下删除对应的文件即可。在支持Markdown编辑器输入文章内容。再执行一下以下命令：

1
2
3
4
hexo clean # 清除生成内容
hexo g   # 生成静态页面
hexo s  # 本地启动
hexo d  # 部署，本地查看没问题可以执行

部署前最好能先执行一下 hexo clean 命令，清除缓存文件 (db.json) 和已生成的静态文件 (public)。在某些情况（尤其是更换主题后），如果发现您对站点的更改无论如何也不生效，您可能需要运行该命令。

另外，如果你的文章暂时不发布可以先保存在草稿里面。生成草稿的方法和文章差不多 hexo new draft "文章标题"，生成后会在 /source/_drafts里看到你的草稿文章。当你想发布时只要执行 publish 命令即可发布到博客。

1
hexo publish [layout] <filename>

绑定域名

hexo d 部署后每次需要重新改域名，为解决这个问题，需在 /source 的目录中创建一个文件，命名为 CNAME（无后缀文件格式），里边的内容写你的域名。只写域名即可。例如www.xxx.com，不需要添加http(s)://。

如果是多个值的配置，在博客根目录的配置文件中找到skip_render字段，添加值'CNAME'，这里我并未配置。

1
2
3
skip_render:
   - '404/index.html'
   - 'CNAME'

Hexo升级

  • 全局升级 hexo-cli，先 hexo version 查看当前版本，然后 npm i hexo-cli -g，再次 hexo version 查看是否升级成功。

  • 使用 npm install -g npm-check 和 npm-check，检查系统中的插件是否有升级的，可以看到自己前面都安装了那些插件

  • 使用 npm install -g npm-upgrade 和 npm-upgrade，升级系统中的插件。

  • 使用 npm update -g 和 npm update --save。

注意 Hexo 版本有较大变化时，升级后可能会出现很多问题，升级前做好相关备份。

Github Actions自动部署

准备工作

Github新建一个私有仓库，专门用来存放Hexo博客源文件。获取一个 GitHub Personal Access Token 用来推送构建好的文件到我们的 GitHub Pages 仓库。源文件：

1
2
3
4
5
6
7
8
9
.
├── config.yml # 网站的配置信息，您可以在此配置大部分的参数。
├── package.json
├── package-lock.json
├── scaffolds # 模版文件夹
├── source  # 资源文件夹
|   ├── _drafts # 草稿文件
|   └── _posts # 文章Markdowm文件
└── themes  # 主题文件夹

点开博客备份仓库上方的 Settings，点到左侧的 Secrets 项，添加四个秘密环境变量 GH_REPO 、GH_USER、GH_MAIL、GH_TOKEN，值分别填写自己的 GitHub Pages 仓库地址（不包含 https:// ）、用户名、邮箱和刚刚申请到的 GitHub Personal Access Token。

准备工作做好后就可以开始编写 GitHub Actions 配置文件了，这里对 Hexo 博客编译部署的步骤进行拆分讲解。

触发条件和运行环境

我们设置在 master 分支上发生 push 操作时触发构建，使用最新的 Ubuntu 系统作为编译部署的环境，同时设置一个全局环境变量将时区修改为 Asia/Shanghai 同步时区，具体的配置内容如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
name: Blog deploy

on:
  push:
    branches:
      - master

env:
  TZ: Asia/Shanghai

jobs:
  blog-cicd:
    name: Hexo blog build & deploy
    runs-on: ubuntu-latest
  steps:

建立工作环境

上面的大前提确定后就可以来开始建立我们的工作环境了（注： 后续所有步骤的配置都是接在上面 steps 块下的，不要弄混了层级关系）。

首先检出代码，设置一下 node 环境，我们这里使用 12.x 版本的 node.js ：

1
2
3
4
5
6
7
- name: Checkout codes
  uses: actions/checkout@v2

- name: Setup node
  uses: actions/setup-node@v1
  with:
    node-version: '12.x'

然后设置一下缓存目录以避免每次都要重新下载，从而加快构建速度（官方不建议直接缓存 node_modules 目录，所以这里设置的是 npm 的下载缓存目录 ~/.npm，这样后面仍需要使用 npm install 来安装依赖）。这里使用的是 package-lock.json 文件的 hash 值来标识缓存是否可以命中：

1
2
3
4
5
- name: Cache node modules
  uses: actions/cache@v1
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

最后就是安装依赖了，这个根据自己的需要操作就行，可使用 gulp 任务来压缩 Hexo 生成的文件，所以这里除了 hexo-cli 还全局安装了 gulp ：

1
2
3
4
- name: Install dependencies
  run: |
    npm install hexo-cli gulp -g
    npm install

生成部署文件

这一步简单点 hexo g 就行了，我这里多加了一步执行 gulp 任务的操作（将其放在两个 step 中而不是一次性执行是为了方便在日志中看到每个操作消耗的时间）：

1
2
3
4
5
- name: Generate files
  run: hexo generate

- name: Execute gulp task
  run: gulp

部署博客

我们先将 GitHub Pages 仓库克隆过来（这里克隆到新建 deploy_git 文件夹内），将其中的 .git 目录移到存放部署文件的 public 目录中（为了保留 GitHub Pages 仓库的提交历史），然后进入 public 目录设置一下提交用户名和邮箱，add 所有文件并提交，最后利用保存在秘密环境变量中的 GitHub Personal Access Token 推送到 GitHub Pages 仓库中就可以了：

1
2
3
4
5
6
7
8
9
10
- name: Deploy blog
  run: |
    git clone "https://${{ secrets.GH_REF }}" deploy_git
    mv ./deploy_git/.git ./public/
    cd ./public
    git config user.name "yourname"
    git config user.email "youremail"
    git add .
    git commit -m "GitHub Actions Auto Builder at $(date +'%Y-%m-%d %H:%M:%S')"
    git push --force --quiet "https://${{ secrets.GH_TOKEN }}@${{ secrets.GH_REF }}" master:master

完整配置文件

这里我并没使用 gulp 任务来压缩 Hexo 生成的文件， 不用执行执行 gulp 任务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
name: Blog deploy

on:
  push:
    branches:
      - master

env:
  TZ: Asia/Shanghai

jobs:
  blog-cicd:
    name: Hexo blog build & deploy
    runs-on: ubuntu-latest

    steps:
    - name: Checkout codes
      uses: actions/checkout@v2

    - name: Setup node
      uses: actions/setup-node@v1
      with:
        node-version: '12.x'

    - name: Cache node modules
      uses: actions/cache@v1
      with:
        path: ~/.npm
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

    - name: Install dependencies
      run: |
        npm install hexo-cli -g
        npm install
    - name: Generate files
      run: hexo generate

    - name: Deploy blog
      run: |
        git clone "https://${{ secrets.GH_REPO }}" deploy_git
        mv ./deploy_git/.git ./public/
        cd ./public
        git config user.name "${{ secrets.GH_USER }}"
        git config user.email "${{ secrets.GH_MAIL }}"
        git add .
        git commit -m "Site updated: $(date +'%Y-%m-%d %H:%M:%S')"
        git push --force --quiet "https://${{ secrets.GH_TOKEN }}@${{ secrets.GH_REPO }}" master:master

Hexo配置

标签外挂

标签外挂的使用需要主题支持此功能，不然其他主题无效，且会报错。我这里使用的主题经过修改后可使用。

note提示块

note提示块提供了simple、modern、flat、disabled四个样式，不可以同时混合样式使用，可在主题目录下_config.yml文件选择样式。

1
2
3
4
5
6
7
8
9
10
11
12
note:
  # Note tag style values:
  #  - simple    bs-callout old alert style. Default.
  #  - modern    bs-callout new (v2-v3) alert style.
  #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
  #  - disabled  disable all CSS styles import of note tag.
  style: flat
  icons: true
  border_radius: 3
  # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
  # Offset also applied to label tag variables. This option can work with disabled note tag.
  light_bg_offset: 0

这里以 style: flat 为例演示， 在文章使用方法如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{% note default %}
默认块标签
{% endnote %}

{% note primary %}
基本块标签
{% endnote %}

{% note success %}
成功块标签
{% endnote %}

{% note info %}
提示块标签
{% endnote %}

{% note warning %}
警告块标签
{% endnote %}

{% note danger %}
危险块标签
{% endnote %}

默认块标签

基本块标签

成功块标签

提示块标签

警告块标签

危险块标签

tabs标签卡

Unique name最好写上，不然编译时会提示，基本使用方法如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{% tabs Unique name, [index] %}
<!-- tab [Tab caption] [@icon] -->
Any content (support inline tags too).
<!-- endtab -->
{% endtabs %}

Unique name   : Unique name of tabs block tag without comma.
                Will be used in #id's as prefix for each tab with their index numbers.
                If there are whitespaces in name, for generate #id all whitespaces will replaced by dashes.
                Only for current url of post/page must be unique!
[index]       : Index number of active tab.
                If not specified, first tab (1) will be selected.
                If index is -1, no tab will be selected. It's will be something like spoiler.
                Optional parameter.
[Tab caption] : Caption of current tab.
                If not caption specified, unique name with tab index suffix will be used as caption of tab.
                If not caption specified, but specified icon, caption will empty.
                Optional parameter.
[@icon]       : FontAwesome icon name (full-name, look like 'fas fa-font')
                Can be specified with or without space; e.g. 'Tab caption @icon' similar to 'Tab caption@icon'.
                Optional parameter.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{% tabs 宗师%}
<!-- tab 黄霑-->
**沧海一声笑**
<!-- endtab -->
<!-- tab 古龙-->
**多情剑客无情剑**
<!-- endtab -->
<!-- tab 金庸@fa fa-hand-o-right-->
**金庸（1924年3月10日—2018年10月30日），本名查良镛，生于浙江省海宁市，1948年移居香港。当代武侠小说作家、新闻学家、企业家、政治评论家、社会活动家，被誉为“香港四大才子”之一，与古龙、梁羽生、温瑞安并称为中国武侠小说四大宗师。**
{% subtabs 小说%}
<!-- tab 射雕英雄传-->
桃花影落飞神剑，碧海潮生按玉箫。
<!-- endtab -->
<!-- tab 神雕侠侣-->
相思无用，惟别而已。别期若有定，千般煎熬又何如？莫道黯然销魂，何处柳暗花明？
<!-- endtab -->
<!-- tab 天龙八部-->
红颜弹指老，刹那芳华，与其天涯思君，恋恋不舍，莫若相忘于江湖..
{% subsubtabs 主角%}
<!-- tab 乔峰-->
坑爹
<!-- endtab -->
<!-- tab 虚竹-->
尼玛
<!-- endtab -->
<!-- tab 段誉-->
你妹
<!-- endtab -->
{% endsubsubtabs %}
<!-- endtab -->
{% endsubtabs %}
<!-- endtab -->
{% endtabs %}

示例效果

沧海一声笑

多情剑客无情剑

金庸（1924年3月10日—2018年10月30日），本名查良镛，生于浙江省海宁市，1948年移居香港。当代武侠小说作家、新闻学家、企业家、政治评论家、社会活动家，被誉为“香港四大才子”之一，与古龙、梁羽生、温瑞安并称为中国武侠小说四大宗师。

桃花影落飞神剑，碧海潮生按玉箫。

相思无用，惟别而已。别期若有定，千般煎熬又何如？莫道黯然销魂，何处柳暗花明？

红颜弹指老，刹那芳华，与其天涯思君，恋恋不舍，莫若相忘于江湖..

坑爹

尼玛

你妹

button按钮

可参考示例代码的使用，基本使用方法如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{% btn [url],[text],[icon],[color] [style] [layout] [position] [size] %}

[url]         : 链接
[text]        : 按钮文字
[icon]        : [可选] 图标
[color]       : [可选] 按钮背景顔色(默认style时）
                      按钮字体和边框顔色(outline时)
                      default/blue/pink/red/purple/orange/green
[style]       : [可选] 按钮样式 默认实心
                      outline/留空
[layout]      : [可选] 按钮佈局 默认为line
                      block/留空
[position]    : [可选] 按钮位置 前提是设置了layout为block 默认为左边
                      center/right/留空
[size]        : [可选] 按钮大小
                      larger/留空。

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
Github website {% btn 'https://github.com/',Github %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,outline %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,outline red larger %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,blue larger %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,block %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,block center larger %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,block right larger %}

<div class="btn-center">
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,pink larger %}
Github website {% btn 'https://github.com/',Github,fa fa-hand-o-right,outline purple larger %}
</div>

演示效果如下，并不代表上面的示例代码。

github github github github github github github

参考

文章作者: Kylen Chan
文章链接: https://booku.ltd/posts/hexo/
版权声明: 本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 Kylen's Blog！
GithubHexo
评论
繁