m5 v0.1 使用帮助
声明:这里不再更新

用 nikola 写静态博客

rca posted @ 2013年2月05日 11:32 in 伪程序猿的行为艺术 with tags nikola 静态博客 , 6853 阅读

放弃 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

 

hbprotoss 说:
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

Avatar_small
rca 说:
2013年3月19日 21:10

@hbprotoss: 要是用 markdown 的话,需要在 nikola 命令后指定文件格式,例如:

nikola new_post -f markdown


登录 *


loading captcha image...
(输入验证码)
or Ctrl+Enter