用 nikola 写静态博客
放弃 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
2013年3月18日 13:45
博主你好,请问为什么我把post_pages改成markdown后,new_post抛异常呢?
Traceback (most recent call last):
File "/usr/local/lib/python2.7/dist-packages/doit/doit_cmd.py", line 102, in run
return self.sub_cmds[command].parse_execute(args)
File "/usr/local/lib/python2.7/dist-packages/doit/cmd_base.py", line 58, in parse_execute
return self.execute(params, args)
File "/usr/local/lib/python2.7/dist-packages/nikola/plugin_categories.py", line 68, in execute
self._execute(options, args)
File "/usr/local/lib/python2.7/dist-packages/nikola/plugins/command_new_post.py", line 152, in _execute
self.site.config['post_pages'])
File "/usr/local/lib/python2.7/dist-packages/nikola/plugins/command_new_post.py", line 55, in filter_post_pages
type_name, compiler))
Exception: Can't find a way, using your configuration, to createa post in format rest. You may want to tweak post_compilers or post_pages in conf.py
2013年3月19日 21:10
@hbprotoss: 要是用 markdown 的话,需要在 nikola 命令后指定文件格式,例如:
nikola new_post -f markdown