用 Hexo 搭建个人博客-02:进阶试验

上一篇中已经用 Hexo 做出了简单的博客。但这仅仅是基础,在基础之上,还有许多工作需要完成,包括但不限于下述问题:

  • 修改 URL 形式
  • 修改导航栏
  • 创建 About 页面
  • 添加 MathJax 支持
  • 添加 Jupyter Notebook 支持
  • ……

请和我一起来解决这些问题。

修改 URL 形式

页面从 md 文件渲染成 HTML 以后,会发现其 URL 形式是 根目录网址/年/月/日/文件名
如果我想要把 URL 形式改成 根目录网址/类别/文件名 怎么办呢?

打开根目录下的 _config.yml(全局配置文件),找到这一行:

permalink: :year/:month/:day/:title/

改成下面这样即可:

permalink: :category/:title/

当然,这要求在每一篇文章的开头都加入 categories: <value> 字段,把 <value> 替换成文章对应的分类。没有该字段的文章,被会分到 uncategorized 分类下。

所有可用于配置 permalink 的变量见 https://hexo.io/zh-cn/docs/permalinks

注:Hexo 没有提供 Pelican 中 slug 这样的变量/配置项,但提供了 :title 这个变量——因此要实现 slug,只要修改文件名,然后在 permalink 中使用 :title/ 即可。

修改导航栏

修改主题文件夹下的配置文件即主题配置文件 _config.yml 中的 nav(或 menu 之类的字段)值即可。

再次提醒:修改的是 主题配置,而非全局配置!!!例如采用 Daily 主题,则修改 blog/themes/Daily/_config.yml

例如,原来为:

nav:
  home: .
  archive: archives
  about: about

效果是

nav01

现在为:

nav:
  home: .
  archive: archives
  category: categories
  about: about

效果是:

nav02

创建 About 页面

键入如下命令:

$ hexo new page about

打开 source/about/index.md,修改该文件的内容。然后渲染生成,即可得到下图效果:

about-01
about-02

添加 MathJax 支持

Hexo 要使用 MathJax 这个 JS 库来实现对 LaTex 公式的渲染,有 2 种方法

1. 使用 Jacman 主题

参考 Jacman 作者原文

首先在博客根目录下执行:

$ git clone https://github.com/wuchong/jacman.git themes/jacman

然后修改根目录下配置文件 _config.yml,注意除了修改 theme 值以外剩下加入的那两行是为了压缩 CSS 文件:

theme: jacman
stylus:
    compress: true

然后在文章开头 front-matter 部分,即类似如下内容的部分中

---
title: test
date: 2016-08-16 10:32:50
tags:
---

加入一个字段 mathjax: true(注意:1.冒号是半角冒号;2. 冒号之后有个半角空格)即可。以上面那个 front-matter 为例,即改成这样:

---
title: test
date: 2016-08-16 10:32:50
tags:
mathjax: true
---

然后就可以在文件中用 LaTex 语法书写数学公式了。

2. 使用其他主题,配合 hexo-math 插件

[2018-12-09 16:02] 注:本文太久没更新了。该插件已过时,新的插件可参考这个方案,具体我还没实验过。

第一,安装 hexo-math 插件:

$ npm install hexo-math --save

第二,也是最奇怪的一点:要在 _config.yml 中添加下述文字:

plugins:
- hexo-math

问题就在于执行完第 2 步后,hexo clean + hexo s -g 无论如何都无法挂到本地,总是提示:

INFO  [hexo-math] Using engine 'mathjax'

甚至无法部署:

$ hexo d
INFO  [hexo-math] Using engine 'mathjax'
ERROR Deployer not found: git

于是 Google 一搜,找到了这里

把plugins 清空就没问题,这两天都在被这问题折腾

于是我就尝试把 _config.yml 中刚加入的 plugins 部分删除,然后成功 hexo clean + hexo s -g + hexo d……

也不知道这是为什么。

增补 20160816:删除博客文件夹从头开始做了 2 遍以上,推测只要执行第 1 步 npm install hexo-math --save 即可,然后就可以在文件中用 LaTex 语法书写数学公式了。

然后我 new 了一篇新文章测试:

$F_{\mu}$
$F_a + F_b = F_c$

渲染成功,如图所示:

MathJax-plugins

3. LaTex 公式渲染与 Markdown 渲染冲突问题

Markdown 解析和 LaTex 公式解析时出现冲突,典型情况就是:如果希望 LaTex 公式中的下划线 _ 解析成功,必须写成 \_ 强制转义。这是说,如下的公式:

$F_a = F_b + F_c + F_{\mu}$

在 Jacman 主题下的渲染效果是:

mathjax-jacman-01

必须写成这样:

$F\_a = F\_b + F\_c + F\_{\mu}$

才能渲染成功:

mathjax-jacman-02

在其他主题下安装 hexo-math 插件的渲染效果也是一样的问题:

badMathJax-01

必须要改成

$F\_a = F\_b + F\_c + F\_{\mu}$

才能正常渲染……

badMathJax-02

但是现在有一个更简单的解法

这个问题有一种更简单的、不用大规模改动 LaTex 公式的解法:使用 {% raw %}{% math %}LaTex Formula{% endmath %}{% endraw %} 来替代 $LaTex Formula$ 的表达,即:

公式是这样的 {% math %} F_a = F_b + F_c + F_{\mu} {% endmath %},你必须理解它,才能看懂下面这些公式:

{% math %}
\begin{aligned}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
\end{aligned}
{% endmath %}

效果就是这样的:

betterMathJax

这个解法来自于这篇文章下方 1MHz路箩筐oaright 的对话给我的启发。

类似的解法还有一个:使用 {% raw %}{% raw %}$LaTex Formula${% endraw %}{% endraw %} 来替代 $LaTex Formula$,使用 {% raw %}{% raw %}$$LaTex Formula$${% endraw %}{% endraw %} 来替代 $$LaTex Formula$$

添加 Jupyter Notebook 支持

参考这篇文章,只要现进入该网站:

nbviewer

在输入框中输入

  • 你的 GitHub 用户名
  • 你的 GitHub 用户名/仓库名
  • Gist ID

点击「Go!」,找到你需要的那个文件,复制此时地址栏的 URL,例如

http://nbviewer.jupyter.org/github/fengdasuk19/MLandDS/blob/master/MachineLearning4Theory_AndrewNg_Coursera.ipynb

然后将该 URL 填入下述代码中,并将该代码放入你的博客文章中即可:

<iframe src="your_URL" width="700" height="400"></iframe>

其中 widthheight 值用于调整 nbviewer 在你的文章中展示的尺寸。效果如图

nbviewer

如果不想用这种嵌入的办法,也可以打开 Jupyter Notebook 将你的交互笔记导出为 md 格式的文件,File -> Download as -> Markdown (.md)。如图

downloadAsMD

自定义首页

Hexo 默认首页是汇总整个站点的所有文章(哪怕是通过分页,也是「汇总」的另一种表现形式而已)。如果我用 Hexo 来部署一个简单的站点,但又不想让首页展示这个汇总页,想让首页展示指定的某个页面,有没有可能呢?

如果你采用的是生成静态页面、然后把静态页面拷贝到 GitHub Pages repo 中的做法进行站点部署,那么对于自定义首页有一种简单的方法:

  1. 使用 hexo new page "diy_index" 创建一个名为 diy_index 的自定义页面。然后随意修改这个页面吧,它的内容就是将来首页的内容
  2. 然后通过 hexo generate 生成静态文件后,把生成的文件全部拷贝到 GitHub Pages repo 中
  3. 删除 GitHub Pages repo 根目录下的 index.html 文件
  4. 移动到 GitHub Pages repo 根目录下,在命令行中创建一个软链接:cd $REPO_ROOT && ln -s diy_index/index.html index.html
  5. 把更新推到 GitHub 上

静待几分钟,就生效了:你将看到,你部署的网站首页不再是所有博客汇总,而是 diy_index 页面内容。

参考资料

  1. 如何生成一篇新的post - layout 为 page 的情况
  2. Hexo搭建Github静态博客
  3. Hexo MathJax插件
  4. 在 Jacman使用 Mathjax 输出数学公式
  5. 在 Hexo 中完美使用 Mathjax 输出数学公式(注意看评论!)
    6.Hexo MathJax插件(过时,请看作者项目 Hexo-math 的 GitHub 页面)
  6. Hexo Troubleshooting - Escape Contents
  7. IPython Notebook: 交互计算新时代
  8. Hexo Docs - 永久链接(Permalinks)

推荐阅读更多精彩内容