放弃 octopress 的原因

之前用过 octopress，一开始感觉很不错，但是后来由于一个叫做 `rubypython' 的包不能正确的识别系统中的两代 python，导致 octopress 在处理文档中的程序代码高亮时发生 #704 错误。一个 ruby 项目底下有一堆 ruby 包的依赖这倒可以忍受，但是依赖一个 python 包并出现这样一个很要命且长期未能很好修复的 bug，就灰常令人不堪了。虽然这个 bug 现在已被修复，但它给我造成的心里阴影却未能磨灭。今日在 gentoo portage 的更新列表中偶然发现 nikola，便果断抛弃 octopress。

nikola 的优点

不依赖 ruby 包，支持 reStructuredText 与 markdown 两种源文档格式。

安装

Gentoo Linux 的仓库中有 nikola 包，直接安装即可：

$ sudo emerge -avt nikola

如果期望 nikola 支持 markdown 源文档，需要开启它的 USE 标记 `markdown'。

如果在其他系统安装 nikola，请阅读 https://getnikola.com/handbook.html#installing-nikola

建立站点

寻找一个风水较好的目录，使用以下命令生成站点的根目录并进行初始化：

$ nikola init 站点名称

例如：

$ nikola init rca

下文会一直使用 SITE_NAME 这个 Shsell 变量指代站点目录名。

然后应当对站点进行一些配置，即修改 $SITE_NAME/conf.py 文件，其中最应当修改的部分为：

BLOG_AUTHOR = "Your Name"
BLOG_TITLE = "Demo Site"
BLOG_URL = "http://nikola.ralsina.com.ar"
BLOG_EMAIL = "joe@demo.site"
BLOG_DESCRIPTION = "This is a demo site for Nikola."

我将其改为：

BLOG_AUTHOR = "rca"
BLOG_TITLE = "伪程序猿的私人领地"
BLOG_URL = "http://rca.github.com"
BLOG_EMAIL = "liyanrui.m2@gmail.com"
BLOG_DESCRIPTION = "非礼勿视，非礼勿言"

如果打算使用 markdown 作为源文档格式，那么需要将 $SITE_NAME/conf.py 文件中的：

post_pages = (
    ("posts/*.txt", "posts", "post.tmpl", True),
    ("stories/*.txt", "stories", "story.tmpl", False),
)

修改为：

post_pages = (
    ("posts/*.markdown", "posts", "post.tmpl", True),
    ("stories/*.markdown", "stories", "story.tmpl", False),
)

之所以如此，是因为 nikola 默认会将后缀为 .txt 的文件视为 reStructuredText 格式。

如果不是对 markdown 格式情有独钟，更推荐使用 reStructuredText 格式，因为 nikola 提供了一些比较有用的扩展标记，例如文档目录、幻灯片等。

第一次写文章

在终端中进入 $SITE_NAME 目录：

$ cd $SITE_NAME

然后删除 nikola 的示例文档：

$ rm posts/*

然后创建你的第一篇文章：

$ nikola new_post
Creating New Post
-----------------

Enter title: 
#=> 请在此输入文章标题

例如，我要创建一份标题为 `测试' 的文章，只需：

$ nikola new_post
Creating New Post
-----------------

Enter title: 
测试

输完文章标题，然后回车，nikola 便会作出以下回应：

Your post's text is at:  posts/ce-shi.txt

是不是很惊讶，nikola 可以将汉字自动转化为拼音，然后将其作为源文档的文件名。

用你惯用的文档编辑器打开 posts/ce-shi.txt 文件，可看到以下内容：

.. title: 测试
.. slug: ce-shi
.. date: 2013/02/05 10:51:46
.. tags: 
.. link: 
.. description: 

Write your post here.

其中前 6 行皆为可被 nikola 解析的文档导言区，它们分别定义了文章的标题、页面名、创建日期、标签、源文件地址、HTML 的 META 标签。

导言区之后是文档区，你可以使用 reStructuredText 标记写文档的内容。

上面所创建的文档之所以要使用 reStructuredText 标记进行撰写，是因为文件的后缀是 .txt，nikola 默认将其识别为 reStructuredText 格式。

如果你想使用 markdown，那么需要告诉 nikola 在生成新的源文档时使用 .markdown 后缀，设置方法见上一节。除此之外，还要在产生新文档时指定文档格式为 markdown，例如：

$ nikola new_post -f markdown$ nikola new_post -f markdown
Creating New Post
-----------------

Enter title: 
再测试
Your post's text is at:  posts/zai-ce-shi.markdown

nikola 生成的 markdown 源文档与 reStructureText 相比，只是在导言区略有不同，前者使用 `<!--' 与 `-->' 符号将导言区囊括了起来。

实际上，nikola 是将 `<!--' 与 `-->' 符号视为 markdown 的注释符，而将 `..' 符号视为 reStructuredText 的注释符。再多说一句，nikola 对 reStructuredText 标记提供的扩展也是以 `..' 符号开始。

将源文档转化为 HTML

源文档的内容撰写完毕后，将其转化为 HTML，只需在 $SITE_NAME 目录中执行：

$ nikola build

如果是第一次写文章，那么这个命令会将 nikola 的使用手册的 reStructuredText 源文档也处理为 HTML，所以屏幕中显示的输出文档有点多。以后如果只是对某一篇文章进行了修改，nikola 便只会更新与之相关的 HTML 文件。

如果你希望将站点中的 HTML 文件再重新生成一遍，可以这样做：

$ nikola build forget
$ nikola build

在本地查看 nikola 页面

nikola 提供了一个运行于本地的网页服务器，在 $SITE_NAME 目录中使用下面的命令开启它：

$ nikola serve

然后在浏览器中地址栏中输入 `http://127.0.0.1:8000' 即可打开你的网站的首页。

更多阅读

在 nikola 本地运行的网页服务器中即可阅读 nikola 的手册，即：http://127.0.0.1:8000/stories/handbook.html

或者阅读官方网站上的手册：https://getnikola.com/handbook.html