Nikola 是我用了 3 年的静态网页生成工具，这个 Github 主页上的所有页面皆由它生成。它的安装与基本用法可参考《Nikola 入门文档》，对于 Linux 环境，建议在 virtualenv + python 3 环境中安装它。它的更详细的用法，见《Nikola 手册》。本文仅记录我在使用 Nikola 过程中遇到的一些小问题以及不甚高明的对策，仅作备忘之用。

自定义首页

Nikola 会自动生成首页，将近期的文章内容收集到一个页面，该页面对应的文件为 index.html。这份文件默认会被放到站点的根目录里，所以，它就成了站点的首页。我觉得 Nikola 这个功能很鸡肋，因为我想自己定义首页，而不是这种自动生成的东西。该怎么办呢？

首先，在 conf.py 文件里，将 INDEX_PATH 设为

INDEX_PATH = "blog"

这样，Nikola 就会将这个自动生成的 index.html 文件放到 站点根目录/blog 目录里，从而令它失去了担当站点首页的资格。理论上，也可以随便取个目录名来用，例如 ·

INDEX_PATH = "obsolete"

用这种乾坤大挪移的办法，算是将这个鸡肋的站点首页「消灭」了。接下来，就是建立一个自定义的首页，以后手工来维护它。方法很简单，只需要在 PAGES 目录，任意建立一份源文件，将其 slug 设为 index.html 即可。

PAGES 目录，就是在 conf.py 文件中设定的目录。例如，我的设定是：

PAGES = (
    ("stories/*.md", "", "story.tmpl"),
)

这就意味着，我可以在 stories 目录建立 slug 设为 index.html 的源文件（至于它对应的文件名是什么，并不重要）。假设这份源文件是 Markdown 格式，那么所谓 slug 就是文件头中的 slug 条目，例如：

<!-- 
.. title: 
.. slug: index
-->

剩下的内容可自由定义。

当网站内容重新发布时，这份源文件就会被转化为网站根目录中的 index.html 文件。因为 Nikola 就是这样对待 PAGES 目录中的源文件的，会把它们「平铺」在网站的根目录里。

图片目录冲突

在 conf.py 文件中，我设定了专门用于放图片的目录 images：

FILES_FOLDERS = {'files': 'files',
                 'meta-doc': 'meta-doc',
                 'mycss': 'mycss',
                 'MathJax': 'MathJax',
                 'images': 'images'} # <<<----- here ----------

但是 Nikola 有个自动缩放图片的功能，它会将自动缩放的图片也存放在一个名为 images 的目录，这样就与我设定的目录发生了冲突，而且 Nikola 在生成网页文件的时候会罢工。

解决这个问题的最简单的办法是禁用自动缩放图片功能，即注释掉 conf.py 文件中的下面几行：

# IMAGE_FOLDERS = {'images': 'images'}
# IMAGE_THUMBNAIL_SIZE = 400
# IMAGE_THUMBNAIL_FORMAT = '{name}.thumbnail{ext}'

数学公式支持

在文章的 Markdown 头部，增加

.. has_math: true

若所使用的 Nikola 主题的模板提供了数学公式支持^{注 1}，那么 Nikola 默认会通过 MathJax 的 CDN 实现数学公式的渲染。倘若在 conf.py 文件中，开启 KaTeX，即

USE_KATEX = True

那么，Nikola 便会通过 KaTeX 的 CDN 实现数学公式的渲染。

注 1：lib/python-版本号/site-packages/nikola/data/theme/主题/templates/math_helper.tmpl 文件。

若想部署本地的 MathJax 或 KaTeX 数学公式渲染支持，只需下载它们的包，放在站点根目录，然后在 conf.py 的 FILES_FOLDERS 中增加相应的目录名，最后修改 Nikola 主题模板中的数学支持语句，将 CDN 换成本地的 MathJax 或 KaTeX 目录。

发布到 Github

若通过 ssh key 发布，记得将 .git/config 中的 url 的值设为

git@github.com:liyanrui/liyanrui.github.io.git