使用Pelican搭建博客系統

摘要

經過幾天的折騰，用Pelican搭建的獨立博客系統終於上線運行了。可以打開kamidox.com看一下效果圖。由於選用了響應式網頁設計的主題，所以在手機上的瀏覽效果也相當贊。本文介紹了Pelican的特性；選擇Pelican的理由以及從頭安裝配置，搭建出一個可運行的獨立博客系統。最後給出我自己的最佳實踐描述。

Pelican介紹

什麼是Pelican

Perlican是用Python實現的一個靜態網站生成器，支持reStructuredText或Markdown。它支持以下功能：

• 博客文章和靜態網頁
• 支持評論。評論是通過第三方服務Disqus支持的。即評論數據保存在第三方服務器上
• 主題支持
• 把博客文章生成PDF格式文檔
• 多語言博客支持，如可以用英文和中文寫同一篇博客。不同語言訪問者訪問相應語言的博文
• 支持Atom/RSS訂閱
• 博文中代碼高亮支持
• 博客搬家支持(WordPress, Dotclear, 或RSS feeds)
• 支持插件，如Twiter, Google Analytics等

爲什麼選擇Pelican

首先排除掉WordPress之類的CMS系統。因爲我不想要數據庫，我只需要一個輕量級的靜態網站生成器。我的博客使用Markdown編寫，且保存在GitHub上。我想要的，只是用Markdown寫完博客之後，git commit + git push即可直接發佈到博客網站上。

這篇文章介紹了32個各種語言實現的博客引擎，而這篇文章介紹了５個最輕量級的靜態網站生成器。最終選擇Pelican是基於如下原因：

• 使用Python實現。由於最近在學習Python，我可以閱讀源碼並按照我的需求來改造Pelican使之完全符合我的需求。下次學習Ruby，用jekyll再折騰一遍。因爲Jekyll是用Ruby實現的。且GitHub Pages的後臺就是用Jekyll，到時可直接用GitHub Pages實現個人博客。
• 足夠輕量級。總的代碼量才1MB多。安裝也方便。
• 有一堆現成的主題可以使用。這對我這種非專業前端的開發者來說，省了不少事。
• 文檔齊全。
• 開發活動活躍。GitHub上代碼提交活躍。上面文章裏介紹的很多博客系統基本上都2+年前就停止更新了。

最後兩點對使用任何開源工具來說都是很重要的，只有開發活躍，社區資源多，文檔齊全，遇到問題的時候才能較快地得到解決。

Pelican安裝與配置

安裝Pelican並創建項目

詳細的信息可以參閱Pelican官方文檔。假設電腦上已經安裝Python和pip。首先，通過pip安裝pelican和markdown：

pip install pelican markdown

然後創建你的博客項目：

mkdir ~/blogs
cd ~/blogs
pelican-quickstart

在運行pelican-quickstart時，系統會問一系列問題，比如你的博客網址啊，作者名字啊之類的，根據真實情況填寫即可，這些問題只是用來生成配置文件的，我們後面都可以通過修改配置文件來手動修改這些設置。我填寫的內容如下：

 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

kamidox@kamidox-laptop:~/lab/blogs$ pelican-quickstart
Welcome to pelican-quickstart v3.4.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

> Where do you want to create your new web site? [.]
> What will be the title of this web site? kamidox
> Who will be the author of this web site? Joey Huang
> What will be the default language of this web site? [en]
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n)
> What is your URL prefix? (see above example; no trailing slash) http://kamidox.com
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10]
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n)
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) y
> What is the hostname of your SSH server? [localhost] kamidox.com
> What is the port of your SSH server? [22]
> What is your username on that server? [root] ubuntu
> Where do you want to put your web site on that server? [/var/www] /home/ubuntu/blogs
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
> Do you want to upload your website using GitHub Pages? (y/N) N
Done. Your new project is available at /home/kamidox/lab/blogs

其中第14行的http://kamidox.com以及第21行的kamidox.com是我的域名，如果你只是在本機試驗，可以填localhost。創建完項目後，目錄下看起來象這樣。

kamidox@kamidox-laptop:~/lab/blogs$ tree
.
├── content     # 這個就是放博客內容目錄，這個目錄及子目錄下的所有md和rst文件將會被轉成html文件
├── develop_server.sh   #這個是用來在本地運行一個服務器來實時查看生成的html文檔的腳本
├── fabfile.py  # 這個是使用Python的fabric來實現文件上傳的工具，即Deploy工具
├── Makefile    # 這個是使用是用來生成網站內容並上傳的工具。後文詳細解釋
├── output      # 這個是從content目錄生成的html目標文件的存放目錄
├── pelicanconf.py      # 這個是本地開發時的配置文件
└── publishconf.py      # 這個是發佈時的配置文件

2 directories, 5 files

配置pelicanconf.py和publishconf.py

Pelican的配置文件是直接用Python寫的，我本地開發配置文件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
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals

AUTHOR = u'Joey Huang'
SITENAME = u"kamidox.com"
SITEURL = 'http://localhost'
DISQUS_SITENAME = 'kamidox'

PATH = 'content'

TIMEZONE = 'Asia/Shanghai'

DEFAULT_LANG = u'zh_CN'
DEFAULT_DATE_FORMAT = ('%Y-%m-%d(%A) %H:%M')

USE_FOLDER_AS_CATEGORY = True
DEFAULT_CATEGORY = 'hide'

# Feed generation is usually not desired when developing
FEED_ATOM = 'feeds/atom.xml'
FEED_RSS = 'feeds/rss.xml'
FEED_ALL_ATOM = None
FEED_ALL_RSS = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None

# menu items
MENUITEMS = [('Home', SITEURL),
            ('About', 'about.html'),]

DEFAULT_PAGINATION = 10
MD_EXTENSIONS = [
        "extra",
        "toc",
        "headerid",
        "meta",
        "sane_lists",
        "smarty",
        "wikilinks",
        "admonition",
        "codehilite(guess_lang=False,pygments_style=emacs,noclasses=True)"]

CNZZ_ANALYTICS = True
MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%m}/index.html'
THEME = "themes/foundation-default-colours"

1. 第6行的SITENAME是博客網站的名稱，可以是任何字符；第7行是博客網站的網址，這個字段在本地開發和發佈版本是不一樣的，本地直接填localhost即可，發佈版本里需要填博客網址。
2. 第8行：我使用了Disqus作爲我的評論系統，Disqus也是YC畢業生。啓用Disqus評論系統非常簡單，在官網上註冊一個Disqus帳戶，然後把帳戶名填在DISQUS_SITENAME值裏即可啓用。我的Disqus帳號剛好也是kamidox。
3. 第33－42行：這裏是配置Markdown擴展，用來支持代碼高亮。並且使用Emacs風格的代碼高亮。
4. 第44行：由於GFW的存在，我把Google Analize換成了國內的CNZZ統計。
5. 第46行：我的博客使用了foundation-default-colours這套主題。關於主題，後文詳解。

開發環境和發佈環境的配置差不多，除SITEURL不一樣外，還多了兩個配置：

SITEURL = 'http://kamidox.com'
# usful setting for publish
RELATIVE_URLS = False   # 禁用相對路徑引用
DELETE_OUTPUT_DIRECTORY = True      # 編譯之前刪除output目錄，這樣保證output下生成的內容是乾淨的

其它的配置項，可以參閱Pelican設置文檔。

配置Makefile

撰寫完博客，並在本地預覽後，需要發佈到服務器上。我使用Makefile的形式來生成文檔併發布。我的Makefile核心代碼如下：

1
2
3
4
5
6
7
8
9

#!/makefile
SSH_HOST=kamidox.com
SSH_PORT=22
SSH_USER=ubuntu
SSH_TARGET_DIR=/home/ubuntu/blogs/
SSH_KEY=/home/kamidox/work/aws/kamidox-key-tokyo.pem

rsync_upload: publish
    rsync -e "ssh -p $(SSH_PORT) -i $(SSH_KEY)" -P -rvzc --delete $(OUTPUTDIR)/ $(SSH_USER)@$(SSH_HOST):$(SSH_TARGET_DIR) --cvs-exclude

1. 第2－4行：指定了要上傳內容的目的服務器的地址，端口以及用戶名
2. 第5行：指定了遠程服務器上保存博客內容的目錄
3. 第6行：我添加的SSH Identity文件路徑。這是因爲Amazon EC2登錄時我是用SSH Identity文件登錄的，而不是使用用戶名和密碼
4. 第8-9行：我使用rsync來進行上傳操作。rsync可以在本地和遠程服務器之間同步文件。同步過程中只同步那些改變了的文件，且傳輸過程中會壓縮數據，它比scp要所需要的帶寬要小。這裏要注意的是，我在默認生成的Makefile上增加了-i $(SSH_KEY)，這個就是指定SSH Identity文件登錄遠程SSH的方法。

配置主題

Pelican支持大量的開源主題，GitHub上的pelican-themes項目有幾十套主題，大部分都帶了效果預覽圖。可以從裏面挑一個你喜歡的主題樣式來使用。還有一個更方便的挑選主題的方式，直接打開www.pelicanthemes.com挑選吧。一個網頁裏就列出了幾乎所有的主題。我的博客是使用foundation-default-colours主題，並在這套主題的基礎上進行了一些定製。選定好喜歡的主題後，從GitHub上下載下來所有的主題：

mkdir ~/pelican
cd ~/pelican
git clone https://github.com/getpelican/pelican-themes.git

從裏面拷貝一份你選中的主題到項目根目錄的themes目錄下，在本文的例子中是~/lab/blogs/themes。然後在pelicanconf.py和publishconf.py裏通過下面代碼指定博客主題：

THEME = "themes/foundation-default-colours"

通常的做法是，選中一個自己喜歡的主題後，會進行一些定製。Pelican使用Jinja2來配置主題。一個主題的典型結構如下：

├── static
│   ├── css
│   └── images
└── templates
    ├── analytics_cnzz.html // 這個是我添加的使用cnzz的統計服務的代碼
    ├── analytics.html      // 這是Google Analytics的代碼
    ├── archives.html       // 這個是博客歸檔頁面的模板
    ├── article.html        // 這個是博客正文的顯示模板
    ├── base.html           //　這個是所有頁面的父類模板，即所有頁面都引用這個頁面。比如網頁導航欄啊之類的，都定義在這裏
    ├── categories.html     //　所有博客文章的分類列表
    ├── category.html       // 某個博客分類的文章列表模板
    ├── index.html          // 主頁
    ├── page.html           // 分頁顯示的模板
    ├── tag.html            // 某類標籤下的文章列表
    └── tags.html           // 所有的標籤列表頁面模板

稍微有點Jinja的知識加上一些HTML和CSS的知識，就可以自己定義主題了。

撰寫博客

撰寫博客

在content目錄下新建一個xxx.md，使用Makedown語法直接撰寫文檔即可。我在ubuntu下使用的是gedit，代碼高亮效果很好。撰寫博客的時候需要注意，Pelican支持一些元數據。比如，本文的元數據如下：

1
2
3
4
5
6
7
8

Title: 使用Pelican搭建博客系統
Date: 2014-10-07 22:20
Modified: 2014-10-07 23:04
Tags: python, pelican
Slug: build-blog-system-by-pelican
Authors: Joey Huang
Summary: 本文介紹了Pelican的特性；選擇Pelican的理由以及從頭安裝配置，搭建出一個可運行的獨立博客系統。
Status: draft

1. 第5行：Slug是文檔的唯一標識，生成html時，會直接使用這個值當html的文件名。所以，不同博客文章這個值需要保證唯一性，否則生成html時會報錯。
2. 第8行：這個表示本文是草稿。比如我們一篇博客經常不是一次性寫完的，寫了一半暫不想讓讀者看到，或者寫完想讓別人幫忙審查一下，就可以加這一行標識。這樣Pelican在處理時，這篇文章也會生成html，但不會放在博客的主頁及分類索引裏，這樣普通的讀者一般看不到這個文章。有這個標識的文章生成時放在output/drafts目錄下，你就可以通過分享url的方式讓你的co-worker幫你review你的文章。

我們可以在content目錄下任意建子目錄來組織管理博客文章。由於我們在設置文件裏指定這個值USE_FOLDER_AS_CATEGORY = True，這樣這些目錄名稱就自動變成博文分類的目錄了。

預覽博客文章

撰寫文章的過程中，可以隨時在瀏覽器裏預覽博客文章。方法是先在博客項目的根目錄下執行下面命令來啓動預覽服務器：

make devserver

這條命令會自動使用pelicanconf.py的配置文件來生成html網頁，同時在本地的8000端口上啓動一個http服務器，供你預覽文章。這樣，直接打開瀏覽器，輸入localhost:8000即可打開本地服務器上的你的博客主頁。比如，撰寫本文時，我就直接在gedit裏碼字，然後在瀏覽器裏輸入http://localhost:8000/drafts/build-blog-system-by-pelican.html來實時預覽效果。需要注意的是，上述命令會在後臺持續監聽content目錄下的內容，如果這個目錄下的內容發生變化，會自動重新生成html頁面。所以，在gedit裏寫完一段內容，切換到瀏覽器，直接刷新一下就可以看到最新的結果了。

當文章寫完後，需要在博客項目根目錄上運行make stopserver來停止這個預覽服務以及數據監控功能。

發佈博客

寫完博客，我們想發佈到網上。這個時候我們就需要一個主機和一個域名，我的獨立博客系統用到的下面資源：

• Amazon EC2主機。一個帳戶可以免費使用一年。可以點擊這裏註冊。
• 申請獨立域名。我是通過阿里雲直接在萬網上註冊的。一年45元。

我的博客運行的軟件環境：

• Ubuntu 14.04 Server版，運行在Anazon EC2主機上
• Nginx

配置Nginx

Ubuntu下安裝Nginx：

sudo apt-get install nginx-full

安裝完成後，編輯配置文件：

sudo vim /etc/nginx/sites-enabled/default

將配置文件替換成如下的內容：

1
2
3
4
5
6
7
8
9

server {
  listen 80 default_server;
  server_name localhost;
  root /home/kamidox/lab/blogs/output;

  location / {
    index index.html;
  }
}

1. 第3行：這個是服務器地址。這裏使用本機作爲測試服務器就填localhost，如果是配置服務器，就要填服務器的域名。比如我的服務器上，這行是配置成kamidox.com。
2. 第4行：這個設置成博客文章的根目錄。這個使用本機作爲測試服務器，所以直接填博客項目的output目錄。如果是在服務器上，我是直接配置成/home/ubuntu/blogs。

配置完成後，重啓一下Nginx服務：

sudo service nginx resart

然後在瀏覽器裏輸入localhost就可以看到博客首頁。在本機驗證成功Nginx配置後，就可以用SSH登錄服務器去配置服務器了。

上傳博客到服務器

直接在項目根目錄下運行下面的命令即可把文章上傳到博客服務器:

make rsync_upload

因爲我們在前文已經配置了Makefile文件。所以運行這個命令之後，就會使用publishconf.py來生成html，並且通過rsync上傳到服務器Amazon EC2服務器的/home/ubuntu/blogs/目錄下。

最佳實踐

我的博客內容託管在GitHub上。當我需要寫一篇文章時，直接打開gedit/sublime開始用Markdown語法碼字。想預覽時，直接運行make devserver，然後在瀏覽器裏輸入文章的URL就可以直接查看了。如果文章寫了一半，還不想發佈，直接加一條元數據Status: draft。然後git commit + git push提交到服務器。等到文章寫完，想發佈了，刪除掉草稿標識；然後git commit + git push先提交到GitHub上；接着運行make rsync_upload即可把博客內容上傳到Amazon EC2主機上。打開kamidox.com確認一下即完成了一篇博文的發佈。