Hexo配置与扩展

本文最后更新于:2024年7月3日 上午

Hello My World 的姊妹篇。

本站基于 Hexo + GitHub 搭建,采用 Fluid 主题。

这篇文章记录了博客的配置历程,包括:主题配置、域名配置、功能扩展。

主题配置

本站采用的是 Fluid 主题,以下的配置在路径 hewei2001/_config.fluid.yml 中可以实现。该文件的介绍参见 主题配置指南。以下仅介绍部分较为特殊的配置,其他内容可在指南中找到。

代码高亮

lib: 选择生成高亮的库,可选项有 highlightjs 和 prismjs,对应下面两组配置。

这里选择 highlightjs,将 style 修改为 Night Owl 风格,将 bg_color 修改为 true 以适配暗色代码框。

其他尝试过的主题还有 Atom One Dark ReasonableVs 2015Github Dark Dimmed,都是不错的暗色风格。

Mac 风格代码块

在 GitHub 的 Issue 发现有人提供了自定义样式实现 Mac 风格代码块的方法,遂尝试之。首先在路径 hewei2001/themes/fluid/source/css 下新建文件 mac.styl,复制以下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.highlight
background: #011627
border-radius: 5px
box-shadow: 0 10px 30px 0 rgba(0, 0, 0, .4)
padding-top: 30px

&::before
background: #fc625d
border-radius: 50%
box-shadow: 20px 0 #fdbc40, 40px 0 #35cd4b
content: ' '
height: 12px
left: 12px
margin-top: -20px
position: absolute
width: 12px

然后在路径 hewei2001/_config.fluid.yml 中找到 custom_css 选项,加入 /css/mac.css 代码,注意这里后缀名依然使用 .css,不然无法识别!

行内代码颜色

默认的行内代码颜色和正文颜色是继承关系,且行内代码背景色也不明显,因此视觉上难以区分。但是配置文件中又没有对应选项可以修改,查阅 GitHub 的 Issue 发现,有人曾提供过一个解决方案。

打开路径 hewei2001/themes/fluid/source/css/_pages/_base 下的 base.styl 文件,找到 code 配置项,修改颜色为 #E05B35

评论功能

Valine 是国内的一款极简风格的评论软件,也是 Fluid 支持的评论软件之一。在 comment 中选择 valine,之后找到相应的配置区域进行如下操作:

进入官网 LeanCloud 完成注册,然后在控制台创建一个项目 Blog.Comments 后,获取密钥(App ID 和 App Key),在对应位置填入。其他内容选项可以在官网找到说明。

访问人数统计

Fluid 主题提供两种网站的 PV、UV 统计数来源:LeanCloud不蒜子。不蒜子不需要申请账号,直接开启即可,但有时候会响应缓慢拖慢整个页面加载。LeanCloud 使用前需要申请账号,由于前面使用评论功能时已经注册,我们这边直接使用就行。

在控制台创建一个项目 Blog.Counter 后,获取密钥(App ID 和 App Key)和大陆服务器地址,填入 web_analytics 配置项中 leancloud API 相关参数。

内置 Tag 插件

Fluid 内置了一些 Tag 插件,用于实现 Markdown 不容易生成的样式,以下仅列出两种常用的使用语法,添加在 md 文件中:

  • 脚注(需要在设置中开启 footnote 才会渲染)
1
2
3
4
5
正文[^1]

## 参考
[^1]: 参考资料1
[^2]: 参考资料2
  • Tag 便签

在 markdown 中加入如下的代码来使用便签,注意头尾标志需要单独一行

1
2
3
4
{% note success %}
文字 或者 `Markdown` 均可
可选便签:primary紫/secondary灰/success绿/danger红/warning黄/info蓝/light黑
{% endnote %}

或者使用 HTML 形式:

1
<p class="note note-primary">标签</p>
  • 行内标签

在 markdown 中加入如下的代码来使用 Label:

1
2
{% label primary @text %}
可选 Label:primary紫/default灰/success绿/danger红/warning黄/info蓝

或者使用 HTML 形式:

1
<span class="label label-primary">Label</span>

折叠块

Fluid 没有支持原生的折叠块,但是可以通过内嵌 HTML 代码实现,为了更加美观,可以用使用 Tag 便签包裹:

点击查看详细推导Surprise!

实现代码为:

1
2
3
4
5
6
7
8
{% note secondary %}

<details>
<summary><b>点击查看详细推导</b></summary>
Surprise!
</details>

{% endnote %}

Latex 数学公式

1
2
3
4
5
post:
math:
enable: true
specific: false
engine: mathjax katex

其中 specific 建议开启:当为 true 时,只有在文章 Front-matter 里指定 math: true 才会在文章页启动公式转换,以便在页面不包含公式时提高加载速度。

由于 Hexo 默认的 Markdown 渲染器不支持复杂公式,所以必须更换渲染器为 MathJax + Kramed。新版的 Fluid 建议使用 MathJax + Pandoc 渲染器,这样就可以避免一系列字符错乱。下面仅介绍 MathJax + Kramed 的配置方法,更推荐的 Pandoc 配置参考官网即可。

1
2
3
4
$ npm uninstall hexo-renderer-marked --save  	# 卸载原渲染器
$ npm install hexo-renderer-kramed --save # mathjax + kramed
$ npm install hexo-renderer-pandoc --save # mathjax + pandoc
$ npm install @upupming/hexo-renderer-markdown-it-plus --save # katex

这里选择 MathJax 而不是 Katex,是因为其对 LaTeX 语法支持全面,且右键点击公式有扩展功能菜单。

但是 Hexo 中会对一些字符转义,使得用 MathJax 渲染公式有时会出错,根据 GitHub 上的 Issue,需要找到路径 node_modules\kramed\lib\rules\inline.js,修改:

1
2
3
4
5
6
7
8
9
// 第11行:取消对 \ 和 {} 的转义 escape
escape: /^\\([\\`*{}\[\]()#$+\-.!_>])/, // 错误的
escape: /^\\([`*\[\]()#$+\-.!_>])/, // 正确的
//第20行:避免下划线 _ 被转义为斜体,而非 LaTeX 下标
em: /^\b_((?:__|[\s\S])+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/, // 错误的
em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/, // 正确的
//第64行:避免反斜杠加竖线 \| 被转义为 |,而非 LaTeX 双竖线
escape: replace(inline.escape)('])', '~|])')(), // 错误的
escape: replace(inline.escape)('])', '~])')(), // 正确的

如果发现 MathJax 公式虽然能显示,但字体异常,右键点击公式,检查是否默认设置了 Math Settings > Math Renderer > CHTML,将其改为 SVG 可以恢复正常。打开博客主题路径 hewei2001\themes\fluid\layout\_partials\plugins\math.ejs,修改如下内容即可:

1
2
// import_js(theme.static_prefix.mathjax.replace('es5/', ''), 'es5/tex-mml-chtml.js')
import_js(theme.static_prefix.mathjax.replace('es5/', ''), 'es5/tex-svg-full.js')

Tips1:在使用数学公式时,应当避免使用两个连续的 {},否则会被 Hexo 解释为特殊标签,从而报错。

Tips2:Hexo 对公式的支持不如 Typora 好,譬如多行公式需要用 \begin{aligned} ... \end{aligned},换行符 \\ 和定位符 &

Tips3:Hexo 中变量的上下标只能用 LaTeX 实现而不能用 Enhanced Markdown 语法。

Tips4:行内公式、公式块里的联立公式,如果含有分数或者大运算符(如求和),需要用 \begin{aligned} ... \end{aligned} 夹住,否则会被渲染器压扁。

Tips5:公式块内如果一行有多个式子,间隙可能会被压缩,需要用 \quad 分隔。

域名配置

自定义域名

有了 GitHub Pages 服务器自带的域名后,还可以到阿里云再购买一个自定义域名,然后将域名解析到博客的域名,具体过程如下:

  1. 注册阿里云,实名认证后在购买下 hwcoder.top 域名。
  2. 打开域名控制台,进入域名解析列表,进入新买的域名,添加两条记录:
    • 主机记录:@;记录类型:A;记录值为 GitHub Pages 域名的 IP。
    • 主机记录:www;记录类型:CNAME;记录值为 GitHub Pages 域名。
  3. 在路径 hewei2001/source 下新建一个 CNAME 文件,里面填写我们买的域名,注意文件不需要任何后缀。
  4. GitHub 中打开对应仓库,在 Setting 中找到 Pages,添加 Custom Domain 为新买的域名,旁边的一个 Enforce HTTPS 勾选后我们的网站就变为 https://hwcoder.top。
  5. 路径 hewei2001/_config.yml#URL 部分,更改为新域名。

以上操作后就可以在自定义的域名访问博客站点了,如果显示的内容与本地服务器查看内容不同,清除浏览器缓存后即可解决。如果不能解决,检查是否以上步骤有错。

部署到 Coding Pages

Coding 可以算是国内的 GitHub,尽管并不是特别流行,但部署到上面可以使国内访问速度更快,还可以提交百度收录(GitHub 禁止了百度的爬取)。

注意:由于 Coding 在前段时间改版后,原有的个人版 Pages 下架,以企业版的形式重新开放,新版的静态网站服务需调用腾讯云对象存储 COS、内容分发网络 CDN、SSL 证书产品等资源,其中 COS 和 CDN 采用用量计费模式。故本博客暂不采用 Coding 部署。

部署到 Cloudflare Pages

无意中发现了 Cloudflare 这个平台在 2021 年初开始提供了静态网页托管的服务,且对免费用户也比较友好。

下面是部署的过程:

  1. 注册 Cloudflare 账户,注册后与 GitHub 绑定。
  2. 绑定账户后可以直接 clone 博客仓库,按照引导选择 Build,等待若干分钟即可,部署后访问 https://hewei2001.pages.dev/ 可以看到博客页面。
  3. 自定义域名设置:输入 hwcoder.top,提示需要进行将 DNS 转移到 Cloudflare 服务器,选择 Free 免费版本。
  4. 更改名称服务器:打开之前购买域名的阿里云,进入域名控制台,选择 DNS 修改,按照 Cloudflare 的提示将原 DNS 服务器修改为指定的内容。
  5. 等待 DNS 转移成功后,重复第 4 步操作,此时 Cloudflare 会自动将 DNS 记录为 A 的那条修改为如下内容:
    • 主机记录:hwcoder;记录类型:CNAME;记录值为 Cloudflare Pages 域名。

通过 Cloudflare 双线部署后,不需要在 _config.yml 文件中加入新的部署仓库,因为自带的 Hook 会在每次部署到 GitHub 后拉取更新。

搜索路径优化

Hexo 博客默认的文章路径是 域名/年/月/日/文章标题,这样的多层目录搜索引擎爬虫爬起来非常费力,平时查阅也很困难,因此需要优化文章的 URL 路径。

打开 hewei2001/_config.yml,找到 permalink 项,将 :year/:month/:day/:title/ 修改为 :name.html,就可以用 域名/文章标题 访问了。

:title:name 的区别是:前者访问时会保留相对于 _post 目录的路径,改成后者后就是纯粹的文章标题。

此外,还可以将下方的 pretty_url 项中的两个 true 改为 false 用于美化 URL,两项分别是去除连接中的后缀 index.html.html 的。

添加百度谷歌收录

如果仅部署在 GitHub Pages,是无法被百度收录的,因为 GitHub 禁止了百度爬虫,最常见的解决办法是进行双线部署。

下面介绍如何提交百度和谷歌搜索:

  1. 进入百度搜索提交入口Google搜索提交入口,登录。百度的提交入口比较隐蔽,需要进入 用户中心 > 站点管理

  2. 输入网站后,需要验证对网站的所有权,有三种验证方式,这里选择「HTML 标签验证」,打开 hewei2001/themes/fluid/layout/_partial/head.ejs 文件,将验证标签放入 <head>...</head> 中。

    1
    2
    3
    4
    5
    <head>
    <meta name="baidu-site-verification" content="code-J3wrn8WJYJ" />
    <meta name="google-site-verification" content="0p_KJKTfB8EcahVDp0vYRjVRhHFw1SBWHi15OakKHY0" />
    </head>
    <!-- 注意每个站点的验证标签都不一样,请勿复制! -->
  3. 重新 hexo d 后,等待数分钟,点击完成验证,就会出现成功提示。

提交搜索后,可以选择添加站点地图使搜索引擎更智能地抓取内容:

  1. 在博客目录下打开 Git Bash,输入如下命令安装:

    1
    2
    $ npm install hexo-generator-sitemap --save
    $ npm install hexo-generator-baidu-sitemap --save
  2. 打开 hewei2001/_config.yml,在最下方添加如下字段:

    1
    2
    3
    4
    5
    # 自动生成sitemap
    sitemap:
    path: sitemap.xml
    baidusitemap:
    path: baidusitemap.xml
  3. 重新 hexo d 后,等待数分钟。

  4. 打开刚才验证网站的页面,找到 sitemap 相关字样,输入:

    • 百度:https://hwcoder.top/baidusitemap.xml
    • 谷歌:https://hwcoder.top/sitemap.xml

完成以上内容后,就可以静待两个搜索引擎的收录啦,其他搜索引擎也同理,在搜索引擎中输入 site:hwcoder.top 就可以实时查看收录结果。

其他功能扩展

以下配置是在 Fluid 主题中不具有的功能,通过各种插件实现。

备份博客到 GitHub

由于 Hexo 博客是静态托管的,所有的原始数据都保存在本地,如果哪一天电脑坏了,或者是误删了本地数据就很危险了。

GitHub 上可以找到一个 hexo-git-backup 插件,但似乎已经不再更新了,仅支持 Hexo 3.x.x 版本,尝试后放弃。

压缩静态资源

博客中有大量 HTML、CSS、JS 文件,这些文件为了阅读方便会加入许多回车和空行,但在页面解析时其实会浪费部分时间,此外如果有许多插图,也会拖慢网页加载,并占据 GitHub 仓库的存储空间。

目前有关插件有 gulphexo-neathexo-all-minifier。推荐采用集成度比较高的 hexo-all-minifier 来实现,由于在安装依赖包过程报错,本站最终采用了 hexo-neat

1
2
$ npm install hexo-all-minifier --save  # 出现 npm ERR! code ELIFECYCLE 错误
$ npm install hexo-neat --save # 换成这个后成功安装

之后在配置文件 hewei2001/_config.yml 中增加如下内容就行:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# hexo-neat
## Docs: https://github.com/rozbo/hexo-neat
neat_enable: true
# 压缩 html
neat_html:
enable: true
exclude:
# 压缩 css
neat_css:
enable: true
exclude:
- '**/*.min.css'
# 压缩 js
neat_js:
enable: true
mangle: true
output:
compress:
exclude:
- '**/*.min.js'
- '**/jquery.fancybox.pack.js'
- '**/index.js'

Hexo配置与扩展
https://hwcoder.top/Hexo-Configuration
作者
Wei He
发布于
2021年8月21日
许可协议