使用Pelican搭建Blog

这篇是我之前用Pelican搭建Blog时写的文章,虽然现在已经迁移到Farbox来了,但还是转过来留存吧。

什么是静态Blog

一直以来搭建独立Blog的首选只有 Wordpress ,不但安装快捷简单,还有无数的插件和主题。甚至有的虚拟空间的运营商还提供一键安装脚本,直接把搭建独立Blog的门槛拉到了0。但是 Wordpress 这种 PHP+Mysql 的方式就是最优的选择嘛?

NO!我需要的只是一个简单的Blog啊,我只要把页面静态的展示出来就可以了,真心不需要那些复杂的功能啊。还有 Wordpress 的编辑器实在是太麻烦太难用了,作为一个坚定的 VIM 党,能用 VIM 写Blog是一件多么幸福的事情啊。最后,找一个免费且稳定的静态空间实在是太容易了,但是找一个免费或稳定的 PHP+Mysql 空间我就只能呵呵呵了。

看来看去和我一样需求的人还真不少, Github 中随便一搜 static blog 就会发现一堆类似 Pelican 的静态Blog生成工具。

静态Blog生成工具的好处:

  • 静态,对托管空间没有要求,只要支持Web服务即可,甚至可以放在 Github 或 Gitbucket 上。

  • 支持 reStructuredText 和 Markdown 语法,这种所想即所得的标记语言加上 VIM ,写Blog真心享受啊。

  • 管理,日志都是文本文件,可以用 Git 方便的管理、进行版本控制。妈妈再也不用担心我的Blog数据丢失了。

  • 内嵌代码支持,使用 pygments 这么棒的工具就不用多说了。

为什么选择Pelican

其实我最早知道的是 Octopress ,但是我对 Ruby 实在是不熟,又没有兴趣为了搭个Blog花时间去研究 Ruby ,于是就在 Github 上去找 Python 对应的解决方案,还真发现了不少。但是要么用的人少,要么不支持 reStructuredText 标记语言。为了少折腾,我还是选了用的人最多的,最流行的 Pelican 。

安装Pelican

官方建议在 virtualenv 下使用 Pelican 。首先安装 virtualenv,并建立 Pelican virtualenv。

1
2
3
4
$ sudo pip install virtualenv
$ virtualenv pelican
$ cd pelican
$ source bin/activate

如果此时 shell 提示符前面多了 (pelican) 这个提示,这就说明已经是在虚拟环境中,在这个环境中可以安装任意的 Python 库,而不用担心会把系统自带的 Python 库搞乱。

从 Github 克隆最新代码安装 Pelican

1
2
3
$ git clone git://github.com/getpelican/pelican.git
$ cd pelican
$ python setup.py install

到此, Pelican 就安装好了。

新建Blog

创建一个文件夹新建Blog

1
2
3
$ mkdir myblog
$ cd myblog
$ pelican-quickstart

根据自身情况回答完所有问题后会生成下列文件::

1
2
3
4
5
6
7
.
|-- content # 所有的文章和图片都放在此目录
|-- develop_server.sh # 用于开启测试服务器
|-- Makefile # 方便管理博客的Makefile
|-- output # 静态文件生成目录
|-- pelicanconf.py # 配置文件
|-- publishconf.py # 发布用的配置文件

新建文章

在 content 目录下新建文件夹,文章便会自动归类到该文件夹名的分类中。

如果要建立页面(比如about页面),在 content 中新建文件夹 pages ,将文件放在该文件夹中即可。

以下用 reStructuredText 来举例,当然也可以用 Markdown 。

Title
#####

:date: 2013-07-15
:tags: tag1, tag2
:category: misc      # 把这个rst文件放在content/misc/下的话, 可以省略这一行
:author: Aken zhang  # 如果在pelicanconf.py文件中指定了作者,那么这一行可以省略
:slug: test          # 这个值是指定生成页面的名称, 比如这个页面的最后生成的名称为test.html

Blog具体内容...

生成Blog

生成Blog非常简单,只需要运行

1
$ make html

即可在 output 目录下生成全站的页面。这时候只要把 output 下的所有文件上传至Web服务器就可以访问了。

使用Github来托管Blog

Github pages 服务大概是目前最好用的免费静态页面托管服务了,还支持绑定顶级域名。虽然300MB的空间略小了点,但如果不大量上传图片,对于个人Blog来说还是足够的。再加上使用Git做版本控制,备份、回退都太方便了。

大致说一下流程,具体就不细说了:

  • 首先注册一个 Github 的帐号。
  • 新建一个 repo ,注意这个 repo 一定要命名为 your_id.github.com ,否则不能成功。
  • 把 output 下的所有文件都上传到这个 repo 的 master 分支下。
  • 耐心等待10分钟,访问 your_id.github.com 就可以打开Blog了。

几点注意:

  • index.html 文件一定要放在 master 分支的根目录下,否则会找不到。
  • 如果要绑定顶级域名。在 repo 的根目录下新建一个名为 CNAME 的文件,文件里写上想要绑定的域名。然后在域名管理的后台设置A记录指向 Github 的IP 204.232.175.90 即可。

进一步的设置

估计折腾到这一步的人都不无法忍受默认主题,我们如何更换主题,修改页面元素呢?

Pelican 的所有配置都在 pelicanconf.py 文件里,我们打开这个文件,修改相应的配置,再重新运行 make html 生成一次页面就可以了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#from __future__ import unicode_literals

AUTHOR = u'aken zhang' # 默认作者名
SITENAME = u':wq akenzc/blog' # Blog名称
SITEURL = 'http://akenzc.com' # 站点的URL

TIMEZONE = 'Asia/Shanghai' # 时区
DEFAULT_LANG = u'zh' # 默认语言
LOCALE = ("zh_CN") # 设置语言环境

# 日期格式
DATE_FORMAT = {
'zh':('zh_CN','%Y-%m-%d, %a'),
}

# Feed generation is usually not desired when developing
# RSS设置
FEED_ALL_RSS = 'feeds/all.rss.xml'
CATEGORY_FEED_ATOM = 'feeds/%s.rss.xml'

THEME = "pelican-octopress-theme" # 主题设置

# Blogroll
# 友情链接
LINKS = (('Pelican', 'http://getpelican.com/'),
('Python.org', 'http://python.org/',)

# Social widget
# 社交网站链接
SOCIAL = (('@akenzc', 'http://weibo.com/akenzc'),)

DEFAULT_PAGINATION = 10 # 默认每一页有多少篇文章
DISQUS_SITENAME = u"akenblog" # 设置disque评论插件的帐号

#Uncomment following line if you want document-relative URLs when developing
#RELATIVE_URLS = True

详细的设置请参考 https://pelican.readthedocs.org/en/latest/settings.html

更换主题

Pelican 更换主题非常方便,只要在 content 同级目录把主题下载下来,然后在 pelicanconf.py 配置文件中的 THEME 字段指定主题的路径和文件夹, 再 make html 重新生成就可以了。

1
2
$ git clone git://github.com/duilio/pelican-octopress-theme  # 我现在使用的主题
$ git clone git://github.com/getpelican/pelican-theres # 更多的主题

使用插件

如果想要使用插件则先要下载一份最新的插件,和更换主题类似同样在 content 同级目录先下载一份最新的插件。

1
$ git clone git://github.com/getpelican/pelican-plugins.git

下载完后,Blog目录下就会多一个 pelican-plugins 目录,然后打开 pelicanconf.py 配置文件中配置插件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
PLUGIN_PATH = u'pelican-plugins'  # 设置插件路径
PLUGINS = ['sitemap', 'related_posts', 'random_article', 'neighbors'] # 设置启用的插件

# 配置sitemap 插件
SITEMAP = {
"format": "xml",
"priorities": {
"articles": 0.7,
"indexes": 0.5,
"pages": 0.3,
},
"changefreqs": {
"articles": "monthly",
"indexes": "daily",
"pages": "monthly",
}
}

# 随机跳转到某日志
RANDOM = 'random.html'

# 相关文章
RELATED_POSTS_MAX = 10

修改完后执行 make html 即可更新插件。

使用静态文件和静态目录

在 pelicanconf.py 里添加 FILES_TO_COPY 项就可以在每次生成html的时候把指定目录下的文件拷贝到 output 目录下。

1
2
3
FILES_TO_COPY = (
("extra/robots.txt", "robots.txt"),
)

上面的配置文件是指把 extra/robots.txt 文件拷贝到 output/robots.txt

在 pelicanconf.py 里添加 STATIC_PATHS 项就可以吧指定的文件夹拷贝到 output 目录下,如果Blog里有图片,这种方法可以很方便的移动存放图片的目录。

1
STATIC_PATHS = [u"img"]

上面的配置文件是指把 img 目录拷贝到 output/static/ 下。

遇到的一些问题

DISQUS无法载入

上传到Web服务器后,评论插件DISQUS无法载入,报以下错误信息:

We were unable to load Disqus. If you are a moderator please see our troubleshooting guide.

解决办法是设置文件 pelicanconf.py 中的 SITEURL 不能为空,设置好站点URL即可。