XieNaoban's Blog
0%

使用 Hexo 搭建 Github 博客

发表于 更新于 阅读次数： 评论次数：
本文字数： 4.9k 阅读时长 ≈ 4 分钟

平台: Windows 10 使用的 Hexo 主题: Next

平台安装

  1. 安装 Git (Git 官网) 并如下配置: 打开Git Bash: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    # 针对你的 Github 账户生成一个 SSH key:
    ssh-keygen -t rsa -b 4096 -C "username@host.com"
    # 按三次回车, 密码设为空
    # 最终在 C:\Users\Username 下生成 .ssh 文件夹并产生 id_rsa, id_rsa.pub 文件

    # 验证 SSH 代理运行:
    eval $(ssh-agent -s)
    # 若正常运行则输出 Agent pid xxxxx

    # 添加 SSH 私钥至代理:
    ssh-add ~/.ssh/id_rsa

    # 复制 SSH 公钥到 Github 账号:
    clip < ~/.ssh/id_rsa.pub
    # 然后网页转到 https://github.com/settings/keys (在登陆的前提下)
    # 点击 New SSH key, title 随意, 在 key 文本框 Ctrl+V

    # 验证 SSH 连接
    ssh -T git@github.com 
    # 显示: Hi Username! You've successfully authenticated, but GitHub does not provide shell access.

  2. 安装 Node.js (Node.js 官网, 安装完即可使用 npm )).

  3. 在 Github 上创建 username.github.io 仓库.

  4. 安装并配置 Hexo: 安装: 

    1
    npm install -g hexo-cli

    (该指令表明 Hexo 为全局安装).

    确定一个空文件夹(必须是空的)作为 Hexo 站点, 在文件夹内右键菜单,选择 "Git Bash Here" 打开 Git Bash, 输入:

    1
    hexo init

    在该文件夹下产生一些 Hexo 文件. 然后打开刚生成的站点配置文件 _config.yml, 必要的修改如下:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    title: XXX's Blog
    author: XXX
    language: zh-CH           # 或 language: en 等等

    theme: next

    deploy:
    type: git
    repo: git@github.com:XXX/XXX.github.io.git
    branch: master

  5. Next 主题安装与配置 安装并配置 Next 主题 (Next 官网, 配置教程官网有). (Hexo 与 Next 主题各有一个 _config.yml 配置文件, 注意区分.)

网站发布至 github.io

在 Hexo 目录安装: 

1
npm install hexo-deployer-git

首先我们可以在本地调试而不急于上传 Github: (同样在 Hexo 目录) 

1
2
3
hexo clean
hexo g
hexo s

执行完毕后打开 http://localhost:4000 即可查看主页. 针对 Markdown, 主题文件的任何修改, 保存后对网页按 F5 刷新立即可查看修改结果. 针对 Hexo 的修改似乎需要重启服务器.

要发布至 Github 则: 

1
2
3
hexo clean
hexo g
hexo d

指令执行完毕即可前往 github.io 查看结果.

踩坑

生成页面

生成新文章页

1
hexo n <post_name>

本质上就是在 source/_posts/ 下生成一个 <post_name>.md 和一个 <post_name> 的文件夹. 其中 md 文件根据模板生成.

生成标签 (Tags) 和分类 (Categories) 页面

默认是没有这些页面的, 当在主页点击标签, 分类页面时会显示 Cannot GET /tags/ 或 Cannot GET /categories/.

生成方法:

1
hexo new page tags

然后进入 source/tags/, 修改 index.html:

1
2
3
4
5
6
---
title: tags
date: 2019-04-11 16:35:04
type: "tags"
comments: false
---

categories, about 等同理.

文章的标题, 发布时间, 与标签等设置与模板

在 Markdown 文件最开头插入如下内容: 

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: 标题标题标题标题
categories:
  - 分类
  - 子分类
  - 子子分类
tags:
  - 标签1
  - 标签2
  - 标签3
abbrlink: 41653
date: 2017-10-22 15:12:50
---

其中 title 必须填写, 不会根据文件名自动生成; abbrlink 是自动生成的, 请勿自己输入; 其余三项可有可无.

Hexo 提供 Markdown 生成模板(仅限使用 hexo n <file_name> 时), 打开 Hexo 站点目录下的 scaffolds/post.md, 若想要生成上述内容可如下填写: 

1
2
3
4
5
6
7
8
---
title: {{ title }}
date: {{ date }}
categories:
  - 
tags:
  - 
---

Markdown 与图片的问题

  1. 在 Hexo 站点文件夹下打开 Git Bash, 输入: 

    1
    npm install hexo-asset-image --save

  2. 打开站点配置文件 _config.yml, 修改: 

    1
    post_asset_folder: true

    以后再使用 hexo n <post_name> 命令新建 Markdown 文件时, 会对应生成同名文件夹, 存放该文件的图片等资源.

    但问题没有被完全解决, 此时在 Markdown 文件引用图片时, 必须以 ![图片](<post_name>/123.png) 的方式引用, 而不能直接 ![图片](123.png).

    PS: Hexo 好像更新了方案! 现在可以直接 ![图片](123.png) 了!

修改文章与网址的映射关系

默认情况每篇文章的链接为: "xxx.github.io/2019/01/01/标题", 这种以标题为组织方式的链接有时候不太好, 以下改为以 CRC 码为组织方式.

  1. 在 Hexo 站点文件夹下打开 Git Bash, 输入: 

    1
    npm install hexo-abbrlink --save

  2. 打开站点配置文件 _config.yml, 修改: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    # URL
    ## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
    url: http://yoursite.com
    root: /
    permalink: posts/:abbrlink.html
    permalink_defaults:
    abbrlink:
      alg: crc16
      rep: dec

开启 LaTeX 公式并修复默认公式渲染的 Bug

  1. 默认 Next 主题不渲染公式. 开启渲染如下: 打开 Next 主题的配置文件 _config.yml, 修改: 

    1
    2
    3
    4
    math:
      enable: true
      per_page: false
      engine: mathjax

  2. 此时发现, 对于多行的公式, 如: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    $$
    \begin{aligned}
    a^{[i+1]} & = z^{[i+1]} \\
    & = w^{[i+1]}a^{[i]} + b^{[i+1]} \\
    & = w^{[i+1]}(w^{[i]}a^{[i-1]} + b^{[i]} + b^{[i+1]} \\
    & = (w^{[i+1]}w^{[i]})a^{[i-1]} + (w^{[i+1]}b^{[i]}+b^{[i+1]}) \\
    & = w'a^{[i-1]} + b'
    \end{aligned}
    $$
    \[ \begin{aligned} a^{[i+1]} & = z^{[i+1]} \\ & = w^{[i+1]}a^{[i]} + b^{[i+1]} \\ & = w^{[i+1]}(w^{[i]}a^{[i-1]} + b^{[i]} + b^{[i+1]} \\ & = (w^{[i+1]}w^{[i]})a^{[i-1]} + (w^{[i+1]}b^{[i]}+b^{[i+1]}) \\ & = w'a^{[i-1]} + b' \end{aligned} \] 渲染出来全挤在一行. 那肯定是不行的.

    试过别的方法如 hexo-renderer-markdown-it-plus, hexo-math, 都不好用. 最好用的还是下面这个:

    首先安装 Pandoc (Pandoc 官网), 然后执行下述指令以替换自带的 Renderer. 

    1
    2
    npm uninstall hexo-renderer-marked --save
    npm install hexo-renderer-pandoc --save

    目前来看还不错.

开启 Markdown 的流程图支持

1
npm install hexo-filter-flowchart --save

自定义非 Hexo 页面

例如我想在 xienaoban.github.io/demo/ 下新建自定义一些网页, 希望 demo 文件夹下的所有网页不受 Hexo 框架影响.

在 Hexo 站点目录打开 Git Bash, 在 source 文件夹下新建 demo 文件夹:

1
hexo new page demo

在 source/demo/ 下建立想要展示的 html 文件.

修改站点配置文件 _config.yml:

1
skip_render: demo/**

生成, 运行, Hexo 会将这些 html 直接复制到 public 文件夹下而不加以处理.

令 Next 主题默认展开所有子目录

打开 Next 主题下的 source/css/_custom/custom.styl, 添加一行

1
.post-toc .nav .nav-child { display: block; }

Hexo 本地搜索功能

于站点目录安装插件

1
npm install hexo-generator-searchdb --save

于站点配置文件添加如下几行:

1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

于 Next 主题配置文件 _config.yml, 修改:

1
2
local_search:
  enable: true

博客置顶

1
2
$ npm uninstall hexo-generator-index --save
$ npm install hexo-generator-index-pin-top --save

然后在 Markdown 中添加 top 字段:

1
2
3
4
5
6
7
8
9
10
---
title: 我的博客
tags:
  - 博客
categories:
  - 博客
abbrlink: 12345
date: 2021-01-28 14:58:38
top: 1
---

给 top 分配不同数值, 数值越高排名越前. 以下是 hexo-generator-index-pin-top 作者的源码:

1
2
3
4
5
6
7
8
9
10
11
12
13
posts.data = posts.data.sort(function(a, b) {
    if(a.top && b.top) { // 两篇文章top都有定义
        if(a.top == b.top) return b.date - a.date; // 若top值一样则按照文章日期降序排
        else return b.top - a.top; // 否则按照top值降序排
    }
    else if(a.top && !b.top) { // 以下是只有一篇文章top有定义，那么将有top的排在前面（这里用异或操作居然不行233）
        return -1;
    }
    else if(!a.top && b.top) {
        return 1;
    }
    else return b.date - a.date; // 都没定义按照文章日期降序排
});