Farseerfc的小窩 - pelican

啓用 GitHub Issue 作爲博客留言系統

2016-08-07T16:28:00+09:00

從今天起本博客將啓用 GitHub Issue 作爲留言系統。原本使用的 Disqus 將繼續保留一段時間，目前沒有關閉的計劃。

換用 GitHub Issue 是計劃了好久的事情了，最初重做這個主題的時候就有考慮過。這個想法的契機是看到了這篇 GitHub hosted comments for GitHub hosted blogs ，然後立馬覺得這個想法很符合寄宿在 GitHub Pages 上的博客。一個限制是要求評論者必須有 GitHub 賬戶，考慮到我的博客的受衆這個要求估計不算太過分。使用 GitHub Issue 的好處麼，比如自帶的 GFMD 富文本格式，郵件通知，還有訂閱和取消訂閱通知，郵件回復，這些方面都不比第三方留言系統遜色。

換用 GitHub Issue 另一方面原因是最近聽說 Disqus 被部分牆了，想必以後牆也會越來越高。之前曾經試過在這個博客換上多說，然而效果我並不喜歡，多說喜歡侵入頁面加很多奇怪的東西，比如用戶的頭像通常是 http 的……也試過結合新浪微博的評論，而新浪微博越來越封閉，API 也越來越不靠譜。

使用 GitHub Issue 作爲評論的方式比較簡單，上面那篇博客裏面提到了，代碼量不比加載 Disqus 多多少，而且沒有了 iframe 的困擾，唯一麻煩的地方就是要稍微設計一下佈局方式讓它融入現有的頁面佈局。我參考上面的實現在這裏。這個加載代碼使用兩個變量加載 Issue Comments ，一個是在 pelicanconf.py 裏的 GITHUB_REPO ，可以指向任何 Repo ，我指向 farseerfc/farseerfc.github.io 的這個 GitHub Page repo ，另一個變量是每篇文章裏需要加上 issueid 的元數據，關連文章到每個 Issue 上。

還有一個稍微麻煩的事情是現在每寫一篇文章之後都要新建一個 issue 了。手動操作有點累人，於是我寫了個腳本自動搜索 pelican 的 content 文件夾裏面文章的 slug 並且對沒有 issueid 關連的文章創建 issue 。

好啦新的留言系統的外觀樣式還在測試中，希望大家多留言幫我測試一下！

2016年8月7日19:30更新

新增了對 GitHub Issue comments 裏面 reactions 的支持，套用 font-awesome 的圖標（似乎沒 GitHub 上的圖標好看）。這個還屬於 GitHub API 的實驗性功能，要加入 Accept: application/vnd.github.squirrel-girl-preview HTTP 頭纔能拿到。

2016年8月7日23:16更新

感謝 @iovxw 的測試讓我發現 github 的高亮回復和郵件回復是需要特殊處理的。高亮回復用上了這裏的 CSS 郵件引言的展開事件直接用 jQuery 做了：

    $(".email-hidden-toggle > a").on("click", function (e){
  e.preventDefault();
  $(".email-hidden-reply", this.parent).toggle();
});

還得注意郵件的回復需要 CSS 裏面 white-space: pre-wrap 。

用 Travis-CI 生成 Github Pages 博客

2015-02-20T11:10:00+09:00

2015年2月21日更新

上次介紹過這個博客改換了主題，本以爲這個話題可以告一段落了，沒想到還能繼續寫呢。

寄宿在 Github Pages 上的靜態博客通常有兩種方案，其一是使用 Jekyll 方式撰寫，這可以利用 Github Pages 原本就有的 Jekyll支持生成靜態網站。另一種是在本地也就是自己的電腦上生成好，然後把生成的 HTML 網站 push 到 Github Pages ，這種情況下 Github Pages 就完全只是一個靜態頁面宿主環境。

我用 Pelican 生成博客，當然就只能選擇後一種方式了。這帶來一些不便，比如本地配置 pelican 還是有一點點複雜的，所以不能隨便找臺電腦就開始寫博客。有的時候只是想修正一兩個錯別字，這時候必須打開某臺特定的電腦纔能編輯博客就顯得不太方便了。再比如 pelican 本身雖然是 python 寫的所以跨平臺，但是具體到博客的配置方面， Windows 環境和 Linux/OSX/Unix-like 環境下還是有些許出入的。還有就是沒有像 wordpress 那樣的基於 web 的編輯環境，在手機上就不能隨便寫一篇博客發表出來（不知道有沒有勇士嘗試過在 Android 的 SL4A 環境下的 python 中跑 pelican ，還要配合一個 Android 上的 git 客戶端）。

當然並不是因此就束手無策了，感謝 Travis-CI 提供了免費的持续整合(Continuous integration) 虛擬機環境，通過它全自動生成靜態博客成爲了可能。

關於 Travis-CI

持续整合原本是敏捷開發(Agile Development) 或者極限編程(Extreme Programming) 中提到的概念，大意就是說在開發的過程中，一旦有微小的變更，就全自動地持續合併到主線中，整合變更的內容到發佈版本裏。這裏的整合實際上可以理解爲 全自動測試 加上 生成最終產品 。可以看到 持續整合 實際強調 全自動 ，於是需要有一個服務器不斷地監聽主線開發的變更內容，一旦有任何變更（可以理解爲 git commit ）就自動調用測試和部署腳本。

於是要用持續整合就需要一個整合服務器，幸而 Travis-CI 對 github 上的公開 repo 提供了免費的整合服務器虛擬機服務，和 github 的整合非常自然。所以我們就可以用它提供的虛擬機爲博客生成靜態網站。

啓用 Travis-CI 自動編譯

這一步很簡單，訪問 https://travis-ci.org/ 並用你的 Github 賬戶登錄，授權它訪問你的賬戶信息就可以了。然後在 https://travis-ci.org/repositories 裏開啓需要編譯的 repo ，這樣 Travis-CI 就會監視對這個 repo 的所有 push 操作，並且對每個 push 調用測試了。

在 Travis-CI 中開啓對 Github Repo 的持續整合

然後在 repo 的根目錄放一個 .travis.yml 文件描述編譯的步驟。暫時測試的目的下我寫的 .travis.yml 大概是下面這樣。

language: python

python:
    - "2.7"

before_install:
    - sudo apt-add-repository ppa:chris-lea/node.js -y
    - sudo apt-get update
    - sudo apt-get install nodejs ditaa doxygen parallel

install:
    - sudo pip install pelican
    - sudo pip install jinja2
    - sudo pip install babel
    - sudo pip install beautifulsoup4
    - sudo pip install markdown
    - sudo npm install -g less
    - wget "http://downloads.sourceforge.net/project/plantuml/plantuml.jar?r=&ts=1424308684&use_mirror=jaist" -O plantuml.jar
    - sudo mkdir -p /opt/plantuml
    - sudo cp plantuml.jar /opt/plantuml
    - echo "#! /bin/sh" > plantuml
    - echo 'exec java -jar /opt/plantuml/plantuml.jar "$@"' >> plantuml
    - sudo install -m 755 -D plantuml /usr/bin/plantuml
    - wget https://bintray.com/artifact/download/byvoid/opencc/opencc-1.0.2.tar.gz
    - tar xf opencc-1.0.2.tar.gz
    - cd opencc-1.0.2 && make && sudo make install && cd ..
    - sudo locale-gen zh_CN.UTF-8
    - sudo locale-gen zh_HK.UTF-8
    - sudo locale-gen en_US.UTF-8
    - sudo locale-gen ja_JP.UTF-8

script:
    - git clone --depth 1 https://github.com/farseerfc/pelican-plugins plugins
    - git clone --depth 1 https://github.com/farseerfc/pelican-bootstrap3 theme
    - mkdir output
    - env SITEURL="farseerfc.me" make publish

Travis-CI 提供的虛擬機是比較標準的 Ubuntu 12.04 LTS ，打上了最新的補丁，並且根據你指定的語言選項會把相應的解釋器和編譯器升級到最新版（或者指定的版本）。這裏用 python 語言的配置，所以 python 是 2.7 的最新版並且有 pip 可以直接用。配置中的 before_install 和 install 的區別其實不大，其中任何一個失敗的話算作 build errored 而不是 build fail ，而如果在 script 裏失敗的話算作 build fail 。

爲了編譯我的模板，還需要比較新的 less.js ，所以添加了 ppa 裝了個最新的 nodejs 並用它裝上了 less 。還從源碼編譯安裝上了最新版的 opencc 1.0.2 ，因爲 Ubuntu 源裏的 opencc 的版本比較老(0.4)，然後 doxygen 作爲 opencc 的編譯依賴也裝上了。其它安裝的東西麼，除了 pelican 之外都是插件們需要的。以及我還需要生成 4 個語言的 locale 所以調用了 4 次 locale-gen 。由於是比較標準的 Ubuntu 環境，所以基本上編譯的步驟和在本地 Linux 環境中是一樣的，同樣的這套配置應該可以直接用於本地 Ubuntu 下編譯我的博客。

寫好 .travis.yml 之後把它 push 到 github ，然後 travis 這邊就會自動 clone 下來開始編譯。 travis 上能看到編譯的完整過程和輸出，一切正常的話編譯結束之後 build 的狀態就會變成 passing ，比如我的這次的build 。

從 Travis-CI 推往 Github

上面的測試編譯通過了之後，下一步就是讓 travis-ci 編譯的結果自動推到 Github Pages 並發佈出來。要推往 Github 自然需要設置 Github 用戶的身份，在本地設置的時候是把 ssh key 添加到 github 賬戶就可以了，在編譯細節都通過 github repo 公開了的 travis 上當然不能放推送用的私有 key ，所以我們需要另外一種方案傳遞密碼。

Github 上創建 Personal Access Token

好在 Github 支持通過 Personal Access Token 的方式驗證，這個和 App Token 一樣可以隨時吊銷，同時完全是個人創建的。另一方面 Travis-CI 支持加密一些私密數據，通過環境變量的方式傳遞給編譯腳本，避免公開密碼這樣的關鍵數據。

首先創建一個 Personal Access Token ，這裏需要勾選一些給這個 Token 的權限，我只給予了最小的 public_repo 權限，如側邊裏的圖。生成之後會得到一長串 Token 的散列碼。

如果你不能使用 travis 命令

2015年2月21日更新

使用 travis encrypt 命令來加密重要數據最方便，不過如果有任何原因，比如 ruby 版本太低或者安裝不方便之類的，那麼不用擔心，我們直接通過 travis api 也能加密數據。

第一步用這個命令得到你的repo的 pubkey ：

curl -H "Accept: application/vnd.travis-ci.2+json" https://api.travis-ci.org/repos/<github-id/repo>/key | python2 -m json.tool | grep key | sed 's/.*"key": "\(.*\)"/\1/' | xargs -0 echo -en | sed 's/ RSA//' > travis.pem

其中的 <github-id/repo> 替換成 github 上的用戶名/repo名，比如我的是 farseerfc/farseer 。travis api 獲得的結果是一個 json ，所以還用 python 的 json 模塊處理了一下，然後把其中包含 key 的行用 grep 提取出來，用 sed 匹配出 key 的字符串本身，然後 xargs -0 echo -en 解釋掉轉義字符，然後刪掉其中的 "<空格>RSA" 幾個字（否則 openssl 不能讀），最後保存在名爲 travis.pem 的文件裏。

有了 pubkey 之後用 openssl 加密我們需要加密的東西並用 base64 編碼：

echo -n 'GIT_NAME="Jiachen Yang" GIT_EMAIL=farseerfc@gmail.com GH_TOKEN=<Personal Access Token>' | openssl rsautl -encrypt -pubin -inkey travis.pem | base64 -w0

替換了相應的身份信息和token之後，這行得到的結果就是 secure 裏要寫的加密過的內容。

然後我們需要 travis 命令來加密這個 token ， archlinux 用戶可以安裝 aur/ruby-travis ，其它用戶可以用 gems 安裝：

$ gem install travis

裝好之後，在設定了 Travis-CI 的 repo 的目錄中執行一下 travis status ，命令會指導你登錄 Travis-CI 並驗證 repo 。正常的話會顯示最新的 build 狀態。然後同樣在這個 repo 目錄下執行：

$ travis encrypt 'GIT_NAME="Jiachen Yang" GIT_EMAIL=farseerfc@gmail.com GH_TOKEN=<Personal Access Token>'

當然上面一行裏的相應信息替換爲個人的信息，作爲這個命令的執行結果會得到另一長串散列碼，把這串散列寫入剛纔的 .travis.yml 文件：

env:
    - secure: "long secure base64 string"

有了這段聲明之後， Travis-CI 就會在每次編譯之前，設置上面加密的環境變量。然後在編譯腳本中利用這些環境變量來生成博客：

script:
    - git config --global user.email "$GIT_EMAIL"
    - git config --global user.name "$GIT_NAME"
    - git config --global push.default simple
    - git clone --depth 1 https://github.com/farseerfc/pelican-plugins plugins
    - git clone --depth 1 https://github.com/farseerfc/pelican-bootstrap3 theme
    - git clone --depth 1 https://$GH_TOKEN@github.com/farseerfc/farseerfc.github.io output
    - env SITEURL="farseerfc.me" make publish

after_success:
    - cd output
    - git add -A .
    - git commit -m "update from travis"
    - git push --quiet

這裏要注意最後 git push 的時候一定要加上 --quiet ，因爲默認不加的時候會把代入了 $GH_TOKEN 的 URL 顯示出來，從而上面的加密工作就前功盡棄了……

根據 travis 的文檔， after_success 裏寫的步驟只有在 script 裏的全都完全無錯執行完之後纔會執行，這正是我們 push 的條件。目前 after_success 的成功與否不會影響到 build 的狀態。具體我用的配置見這裏的最新版。在我的 make github 中調用了 git push 命令，從而執行了 make github 之後就會自動部署到 github 上。

用 Web 編輯並發佈靜態博客

經過以上設置之後，一切正常的話，每次對主 repo 推送更新的同時， Travis-CI 就會自動拉來更新然後編譯並發佈了。可以放置這樣的圖標在項目的 Readme.md 中顯示編譯狀態。

這樣設置之後的另一個好處就在於可以利用 Github 的 Web 界面編輯文章內容。在 Github 裏編輯和保存之後會自動作爲一個 commit 提交，所以也會觸發 Travis-CI 的自動編譯。

在 Github 的 Web 界面中直接編輯文章內容

以及雖然目前還沒有好用的 Github 的手機客戶端，不過直接用 Android/iPhone 的瀏覽器登錄 github 並編輯文章的可用性也還不錯，所以同樣的方式也可以直接在手機上發佈博文了。

That is all, happy blogging ~

換到 farseerfc.me 域名

2015-01-26T23:32:00+09:00

上個月就在狗爹(godaddy) 上買了個自己的域名 farseerfc.me 準備用在這個博客上，當時試着轉到過這個域名，發現自定義域名(custom domain) 只支持 http 不支持 https ，想着還要買自己的證書，於是就扔在了一旁。不用自定義域名的話，放在 github.io 上是可以用 HTTPS 的。今天在 #archlinux-cn 上受大牛 quininer 和 lilydjwg 點播，發現 cloudflare 有提供免費的支持 SSL 的 CDN 服務趕快去申請了一個，感覺非常讚，於是就換過來了。

設置的方法按照這篇博文說的一步步做下來，如它所述，用 CloudFlare 的優點如下：

CDN 加速
SSL (HTTPS) 加密
支持 SPDY 協議
支持 IPv6

2015年12月29日更新

現在不光支持 SPDY 而且支持 HTTP/2 了。

然後 免費賬戶 的一些缺點有：

CloudFlare 和 github.io 之間的數據不是加密的，因爲 github 自定義域名(custom domain) 還不支持使用自己的證書。這也是一開始我沒用自定義域名的原因嘛，這沒有辦法……
CloudFlare 給免費賬戶簽名的 SSL 證書比較新，不支持一些老的設備和瀏覽器，比如不支持老的 XP 系統的 IE 或者 2.x 的 Android。這種情況下沒辦法只能用沒有加密的 HTTP 了。
不支持 HSTS 頭，所以不能從服務器這邊強制瀏覽器用 HTTPS。當然可以放個 javascript 跳轉，也可以用 HTTPSEverywhere 這種方案。

2015年12月29日更新

如評論中提到的現在支持 HSTS 了。

設置步驟

基本按照默認的選項下一步就可以了。

和那個博主一樣我把安全級別(Security profile) 降到了 Low ，即使是可疑流量也不會要求輸入 CAPTCHA 。
把 SSL 方式開在 Flexible SSL，訪客到 CloudFlare 是加密的，而 CloudFlare 到 github.io 是不加密的。
把 CDN 開到了 CDT+Full Optimization ，可以對訪問加速。由於是完全靜態的博客，沒有動態變化的內容，所以應該比較安全。
服務器設置的一步需要將域名解析服務器(DNS nameservers) 從狗爹的服務器改到 CloudFlare 的，如下圖：

更改狗爹的域名服務器

申請好之後就由 CloudFlare 接管域名解析了，接下來在 CloudFlare 的 DNS 設置添加一條 A 類規則指向 github pages 的 IP 。

更改CloudFlare的DNS規則

等一切都反映到 DNS 服務器上就設置完成了，接下來給 farseerfc.github.io push 一個 CNAME 文件寫上我的域名就可以了。我用 Makefile 配合我的 pelican 配置做這個：

publish: rmdrafts cc clean theme
  [ ! -d $(OUTPUTDIR) ] || find $(OUTPUTDIR) -mindepth 1 -not -wholename "*/.git*" -delete
  rm -rf cache
  echo $(SITEURL) > content/static/CNAME
  $(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(PUBLISHCONF) $(PELICANOPTS)
  $(MAKE) rsthtml

github:
  (cd $(OUTPUTDIR) && git checkout master)
  env SITEURL="farseerfc.me" $(MAKE) publish
  (cd $(OUTPUTDIR) && git add . && git commit -m "update" && git push)

SITEURL = '//' + getenv("SITEURL", default='localhost:8000')
STATIC_PATHS = ['static', 'images', 'uml', 'images/favicon.ico', 'static/CNAME']
EXTRA_PATH_METADATA = {
    'images/favicon.ico': {'path': 'favicon.ico'},
    'static/CNAME': {'path': 'CNAME'}
}

然後把生成的靜態網站 push 到 github 之後可以從項目設置裏看到域名的變化：

Github 配置好自定義域名之後的變化

最後把Disqus的評論也遷移到新的域名，disqus有方便的遷移嚮導，一直下一步就可以了。

這樣就一切都設置妥當了。

致謝

最後要感謝提供消息的 quininer 和 lilydjwg ，感謝撰寫設置步驟的 Jonathan J Hunt ，感謝 CloudFlare 提供免費 SSL CDN 服務，感謝 Github 提供方便免費的 Pages 託管。

重新設計了 Pelican 的主題與插件

2015-01-25T22:45:00+09:00

2015年2月14日更新

前言: 新天新地，將一切都更新了 [1]

不知不覺間放任這邊長草很久了，從上次折騰主題到現在都快三年了，而從上次寫了篇告白信到現在也有快兩年了。這期間曾經把主題配色從 Bootstrap 2 默認的白底黑字改成了讓眼睛更舒適的黑底白字，也不過是用 drop-in 的配色方案而已，沒有本質上的改進。

洞中一日世上千載，兩年裏 Bootstrap 已經升上 v3.3 , 而 Pelican 則已經升到 3.5 了。早就眼饞 Bootstrap 和 Pelican 中的諸多新功能新設計，不過無奈於時間有限只能飽飽眼福。

近日想寫的東西越積越多，終於下定決心花了前前後後 兩個月 的時間重新設計了一遍 Pelican 的主題，配合一些我覺得有用的插件。於是本博客就變成你們現在看到的樣子了。（以及本篇博文也用了兩個月的時間寫完，其間還發了幾篇別的短文，算是恢復寫博客的嘗試吧。）

在邁阿密參加 ICSR 2015 的時候拍到的街邊一家叫 Pelican 的旅館

Bootstrap 3 的新設計

全新的優先移動設備(mobile-first) 響應式(responsive) 設計。原本Bootstrap 2雖然有響應式設計，不過諸多細節不能符合我的需求，最終還是得手工 hack @media 查詢去微調。現在的優先移動設備(mobile-first) 響應式(responsive) 柵格系統(grid system) 則相對顯得科學很多了，也終於能在手持設備上看起來舒服一些。諸位可以嘗試改變窗口寬度，或者在不同的手持設備上打開這個 blog ，體驗一下這個頁面在不同顯示器大小中的效果。如果仍有問題歡迎發 Issue 給我。
科學的導航欄(Navbar) 。比 Bootstrap 2 那個科學很多了。無論是保持(sticky) 在上端還是跟着浮動，或者像這邊這樣自動隱藏都很簡單。

更多細節參考 Bootstrap 3 主頁。

Pelican 3.5 的新功能

Python 2 和 Python 3 統一代碼：再沒有惱人的 unicode 相關的問題了。這對 blog 系統來說相當重要啊。而且還能方便切換 pypy 等不同的解釋器。
全新的插件系統：非常多功能強大的插件等着你。
增強了導入系統：嗯總算可以導入我的中文的 wordpress 博客了。（雖然那邊長草更久了……）
站內鏈接：不用硬編碼(hard code) 目標頁面的鏈接了，可以直接寫源文件的位置然後讓 pelican 處理，這樣能簡化各種插件(plugin) 和主題(theme) 的實現。

更多細節參考 Pelican 文檔。

新的文件夾佈局

Pelican 的新文件夾佈局


.
├── cache             生成頁面的 pickle 緩存
├── content           讀取的全部內容
│   ├── <categories>      按分類存放的文章
│   ├── pages             像 About 這樣的固定頁面
│   └── static            文章內用到的靜態內容
├── drafts            文章的草稿箱
├── Makefile          生成用的 makefile
├── pelicanconf.py    測試時用的快速 Pelican 配置
├── publishconf.py    部署時用的耗時 Pelican 配置
├── output          -> ../farseerfc.github.io
├── plugins         -> ../pelican-plugins
└── theme           -> ../pelican-bootstrap3

之前的博客仍然留在 github 上，其中的內容完全搬過來了。開始寫老博客的時候 Pelican 版本較早，沒有形成好的文件夾佈局，導致生成的文章、使用的模板和撰寫的內容全都混在一起，非常難以管理，於是趁改版之際用了新的文件夾佈局方式，並分爲 4 個 git repo 分別管理歷史。

首先是存放總的博客內容的 repo ，其佈局是如圖那樣的。這樣將生成的靜態網站和生成網站用的配置啦內容啦分開之後，頓時清晰了很多。

然後這個內容 repo 中的三個符號鏈接分別指向三個子 repo（沒用 git submodule 管理純粹是因爲偷懶）。 theme 指向 pelican-bootstrap3 ，是我修改過的 pelican 主題。 plugins 指向 pelican-plugins ，由於 plugins 的質量有些參差不齊，其中不少 plugin 都按我的需要做了些許修改，一些是功能改進，另一些則是修bug（比如不少plugin只支持 python 2）。最後 output 指向 farseerfc.github.io 也就是發佈的靜態網站啦。

接下來從主題和插件兩個方面介紹一下改版的細節。

主題： Material Design 風格的 Bootstrap 3

上篇博文就總結了我爲了這個博客尋找了一堆 CSS 框架，並且最終決定用 bootstrap-material-design , DandyDev/pelican-bootstrap3 和 Bootstrap 3 這三個項目結合的方式實現這個模板的主題。這三個項目都或多或少經過了我的修改，修改後的項目以 pelican-bootstrap3 爲基礎放在這裏，包括 Bootstrap3 樣式和 Material 樣式。

對 Bootstrap 3 的定製

由於架構完善，修改 Bootstrap 3 感覺非常簡單。另一方面我在 Web 前端技術上的技能點也不多，所以修改的地方非常有限，只能按我自己的需求定製而已。

響應式設備的大小

修改了 Bootstrap 3 響應式設備的大小

@screen-xs:     320px;
@screen-sm:     598px; /*  768px; */
@screen-md:     952px; /*  992px; */
@screen-lg:    1350px; /* 1200px; */
@screen-xl:    2030px;
@container-sm:  582px; /*  750px; */
@container-md:  930px; /*  970px; */
@container-lg: 1320px; /* 1170px; */
@container-xl: 1990px;

首先把 Bootstrap 3 默認適配的幾個響應式設備的大小改成了我需要的大小。 xs 和 sm 的大小分別按照我的手機屏幕豎屏和橫屏時候的瀏覽器頁面寬度來算， md 是想兼容 Nexus 7 橫屏 960 的寬度以及一個常見上網本 1024 的寬度。 lg 的大小則按照常見的筆記本 1366 寬的屏幕來適配。

這裏 Bootstrap 3 支持的設備大小的一個問題是，它最多考慮到 1200 像素寬的顯示器，而更寬的比如 1600、 2048 甚至 2560 像素寬的顯示器現在也並不少見，其結果就是頁面中左右兩側有很大的空間被浪費掉了。作爲深受這一問題困擾的用戶之一，我用這裏介紹的方法給 bootstrap 增加了一類「比大更大(bigger than bigger) 」的 xl 響應式設備尺寸，寬度設爲支持 2048 像素寬的顯示器，具體的修改反映在 variables.less 文件裏。

根據寬度自動分欄和瀑布式佈局

接下來目標是讓主頁的文章列表像 Google+ 主頁那樣根據顯示器寬度自動調整分欄，使得寬度不同的顯示器上每個分欄的寬度接近。想要達到的效果是，根據上面定義的屏幕寬度尺寸：

xs 用單欄流動(fluid) 佈局 sm 用上方單欄文章列表、下方雙欄側邊欄(sidebar) 固定佈局 md 用單欄文章列表、單欄側邊欄固定佈局

導航欄(Navbar)

文章

側邊欄

底欄

導航欄
文章
側邊欄 1	側邊欄 2
底欄(footer)

導航欄
文章 1	側邊欄 1
文章 2	側邊欄 2
底欄(footer)

lg 用雙欄文章列表、單欄側邊欄固定佈局 xl 用三欄文章列表、雙欄側邊欄固定佈局

導航欄
文章 1	文章 3	側邊欄 1
文章 2	文章 4	側邊欄 2
底欄(footer)

導航欄
文章 1	文章 3	文章 5	側邊欄 1
文章 2	文章 4	文章 6	側邊欄 2
底欄(footer)

一開始純粹用 Bootstrap3 的響應式柵格實現這個分欄佈局，結果發現效果不太理想，因爲文章列表和側邊欄的高度是變化的，會導致柵格間留下大片空白。後來改用這裏示範的純CSS瀑布式佈局實現文章和側邊欄的佈局，具體的實現代碼在 waterfall.less ，總算達到了想要的佈局了。

正文的樣式

最最重要的是文章正文的樣式。這裏我想要達到的效果是，在大屏幕上用更大的字號，讓讀者看起來更舒適，同時在小屏幕上用比較小的字號，最終保證基本上「一行」的文字數接近。這個修改主要針對 .jumbotron ，用了不太科學的方式代碼太長就不貼全了。

一些細微的定製

把主題配色改成了現在這樣的淡紫色 @brand-primary: darken(#6B5594, 6.5%); ，配合我的頭像風格，這個修改只需要一行。接着刪掉了 .btn 的 white-space: nowrap; 讓按鈕的文字可以換行，這也只是一行修改。

2015年1月29日更新

另外我也不太喜歡 Bootstrap 3 默認在手機上的摺疊導航欄(collapsed navbar) ，摺疊之後的操作不夠直觀方便而且依賴 javascript 所以有 bug …… 於是我把它關掉了，具體方式是在 variables.less 把 @grid-float-breakpoint 和 @grid-float-breakpoint-max 都設爲0就可以了。

對 bootstrap-material-design 的定製

這裏定製的地方不多。原樣式中一個不太科學的做法是所有 .btn 都強制加上了陰影效果，這在已經有陰影的環境裏用的話非常礙眼，像是 Win9x 風格的厚重睫毛膏。既然可以單獨給每個樣式加陰影，於是就把 .btn 強制的陰影去掉了，只保留鼠標懸停之後強調的陰影。

其它定製的細節麼就是統一配色風格，修補漏洞錯誤，微調響應式效果而已，這裏不細說。

將以上兩者整合在 pelican-bootstrap3 裏

Pelican 實現顯示源代碼按鈕

顯示源代碼按鈕借用了 Pelican 配置中自帶的 OUTPUT_SOURCES 選項將源文件複製到輸出文件夾：

OUTPUT_SOURCES = True
OUTPUT_SOURCES_EXTENSION = '.rst'

然後在 Makefile 裏用 pygmentize 把所有源代碼文件着色：

find -iname "*.rst" | parallel -I@  pygmentize -f html -o @.html @

最後在按鈕按下的時候用 jQuery 載入源代碼：

<a onclick="$.get('{{SITEURL}}/{{article.slug}}.rst.html', function(data){$('#source-code').html(data)});$('#article-content').toggle();$('#source-content').toggle();">

雖然難看的 hack 比較多，但是能用！

雖說 pelican-bootstrap3 是我 fork 出來的，不過由於我修改的地方實在太多，代碼看來基本上接近重寫了一份。好在之前有給 pelican 寫 bootstrap 2 主題的經驗，這次修改算得上駕輕就熟。可以對比一下上游作者的博客和這裏的樣子體會一下感覺。具體修改過的地方包括：

套用 bootstrap-material-design 的各個元素樣式。
在文章列表模板應用上面提到的 Bootstrap 3 的柵格佈局和瀑布式佈局。
翻譯到多個語言，這裏在後面的 i18n-subsite 插件裏詳述。
套用後面會介紹到的各種插件。
統一側邊欄的樣式到一個模板裏。
添加 Atom 訂閱按鈕和 breadcrumb 條。
對正文中出現的插圖，添加點擊放大的功能，通過 Bootstrap 的 modal 實現。
上面提到的用這個bootstrap插件讓導航欄自動隱藏。
顯示源代碼按鈕 ，也就是每篇文章信息欄中的按鈕。

插件: 發揮 Pelican 和 reStructuredText 的優勢

先列舉一下我目前用到的所有插件：

PLUGINS = ["i18n_subsites",
           "plantuml",
           "youku",
           "youtube",
           'tipue_search',
           'neighbors',
           'series',
           'bootstrapify',
           'twitter_bootstrap_rst_directives',
           "render_math",
           'extract_toc',
           'summary']

嗯其實不算多。接下來逐一介紹一下這些各具特色的插件。

i18n-subsites

這個插件的目的是創建國際化(internationalization) 子站(subsite) 。

之前介紹 Pelican 配置的時候就提到過，原本的 Pelican 就支持一篇文章用多種語言書寫，有 lang 屬性註明這篇文章使用的語言，以及 slug 屬性註明多語言的翻譯之間的關聯，換句話說同一篇文章的多個語言版本應該有相同的 slug 和不同的 lang 。然後原本 Pelican 裏對多語言的實現方式是，首先有一個 主語言 是模板和大部分文章採用的語言，文章列表中會優先列出用 主語言 撰寫的文章，然後從 主語言 的文章鏈接到別的翻譯版本。很多博客系統和CMS對多語言的支持都是這樣的，這種處理方式的缺點也顯而易見：作爲 主語言 的語言必須足夠通用，纔能讓進來的人找到合適的翻譯版本，所以通常 主語言 都是英語。

而這個插件做的事情描述起來很簡單：將文章按語言屬性分到多個子站，每個子站獨立放在各自的文件夾。比如主站是 https://farseerfc.github.io/ 的話，那麼英語的子站就可以是 https://farseerfc.github.io/en/ 。然後分別對多個子站生成靜態頁面。具體的實現方式是對 pelican 的頁面生成步驟做了拆分：

pelican 按正常情況讀入文章，生成元信息。
i18n-subsites 針對每個語言，覆蓋掉 pelican 的一些選項設置比如路徑和 URL ，分別調用 pelican 的頁面生成器按模板生成文章。
對共用的靜態內容比如模板的 js 和 css 文件，只在主站中生成，子站中的相應鏈接全部鏈回主站。

雖然描述起來簡單，但是這個插件可以說最大化利用了 Pelican 的插件系統，實現細節相對比較複雜，大概是我用的這些插件裏面最複雜的了。不誇張的說 Pelican 3.4 支持的新插件 API 和站內鏈接功能基本上就是爲了配合這個插件的。至於具體它會覆蓋哪些 Pelican 的配置，請參閱它的 README.md文件。

按內容拆分多語言子站的做法只解決了問題的一半，還留下另一半的問題，也即對模板的翻譯。對這個問題， i18n-subsites 提供了兩套方案供選擇：

用覆蓋配置路徑的方式讓每個子站套用不同的模板。這配置起來簡單，但是對模板維護起來有點困難。
用 jinja2 的 i18n 插件，配合 Python 的 gettext 庫實現內容翻譯。這個方案配置起來比較複雜，但是配置好之後用起來就很方便了。只是要記得每次修改了模板都要更新翻譯，處理 *.po 和 *.mo 文件等等瑣碎事宜。

這裏我用 jinja2 的 i18n 插件的方式實現了模板的翻譯，各個語言的翻譯在這裏，然後用這裏的 SCons 腳本根據內容是否變化自動更新 po 和 mo 文件。

配置好這一套方案之後，還要注意在模板和文章中處理好鏈接。用 Pelican 3.4 之後推薦的新的文章間鏈接的寫法以及將 SITEURL 設置爲實際 URL 並且關閉 RELATIVE_URLS 之後，應該就不會出沒什麼問題了（可能還要考慮使用的模板和插件的兼容性，大部分都是寫死了 URL 的問題）。

plantuml

嵌入 PlantUML 的示例

PlantUML 是一個Java實現的，用接近文字描述的語言繪製 UML 圖或者 GUI 界面圖的工具，非常適合嵌入在 Markdown、 reStructuredText、 AsciiDoc 等這種輕量級標記語言裏。然後麼這個 plantuml 插件就是定義了一個新的 reStructuredText 指示符(directive) .. uml:: ，把嵌入的內容提取出來調用 plantuml 命令處理成圖像然後再插入到文章中。

比如示例裏的這個 UML 圖就是用這樣一段簡單的文字描述生成的：

.. uml::

    Object <|-- ArrayList

    Object : equals()
    ArrayList : Object[] elementData
    ArrayList : size()

實際用起來這個插件實現上稍微有點小問題：首先它只支持 python2，所以我把它改寫成了 python 2 和 3 都通用的語法；其次它原本輸出的文件夾似乎會被 pelican 刪掉，所以把它改了個位置；然後它輸出的 URL 也和 i18n-subsites 插件間有不兼容的問題，也順帶修掉了。修改之後的代碼在這裏。

2015年1月30日更新

嵌入 Ditaa 的示例

plantuml 是繪製UML的，除此之外還有一個類似的工具是繪製一般的流程圖(diagram) 的，叫 ditaa ，和 plantuml 非常像，也比較像 reStructuredText 的表格。於是我也照貓畫虎實現了一個 ditaa 的指示符(directive) ，用起來類似這樣：

.. ditaa::

                       +-------------+
                       |   ditaa     |-------+
                       |  Diagram    |       |
                       +-------------+       | PNG out
                           ^                 |
                           | ditaa in        |
                           |                 v
     +--------+   +--------+----+    /----------------\
     |        | --+   Pelican   +--> |                |
     |  Text  |   +-------------+    | Beautiful Blog |
     |Document|   |   !magic!   |    |                |
     |     {d}|   |             |    |                |
     +---+----+   +-------------+    \----------------/
         :                                   ^
         |          Lots of work             |
         +-----------------------------------+

render-math

嵌入公式的示例

示範行內公式 $A_\text{c} = (\pi/4) d^2$.

整行公式

\begin{equation*} \alpha{}_t(i) = P(O_1, O_2, \ldots O_t, q_t = S_i \lambda{}) \end{equation*}

這個插件提供在 reStructuredText 中用 LaTeX 語法插入數學公式的能力，定義了 :math: 行內角色(role) 和 .. math:: 指示符(directive) 。實際工作的渲染庫當然是大名鼎鼎的 MathJax ，這個插件會用 MathJax 的 CDN 載入，所以也沒有額外的依賴文件。（只是不知道是否會被國內牆掉，如果公式顯示不正常請務必告訴我。）

youtube 和 youku

顧名思義，這兩個插件分別實現嵌入 youtube 和 youku 視頻。其中 youtube 是原本就有的插件， youku 是我照貓畫虎抄的。之前寫了一篇 KDE5 Plasma 之跳動賣萌的活動按鈕用到了這兩個插件。

tipue_search

Tipue search 是一個非常有意思也很強大的搜索工具，通過 jQuery 實現靜態博客的站內搜索功能。實現方式是，它需要你寫一個 json 文件，包含整個網站的全部文章的標題和文字內容，然後在搜索的時候讀入這個 json 做搜索（是不是有點耍賴）。雖然聽起來會有性能問題，但是應用在小型的靜態博客上效果意外很不錯，比如本站的所有文章內容放在一起的 json 也只有 300KiB 左右。

這個插件就是自動在 pelican 輸出完全部靜態網頁之後，調用 beautifulsoup4 從所有網頁中抽取出純文本，產生這個 json 給 Tipue 用。

neighbors 和 series

這兩個插件比較類似也都比較簡單， neighbors 提供一篇文章的前後文章信息，在主題模板裏可以用來製作 上一篇 和 下一篇 按鈕。 series 提供將多篇文章歸類爲一個系列的支持，當然也需要在主題模板中定義顯示「文章系列」的列表。這兩個插件的效果都能在本文末尾，評論區上方的部分看到。

bootstrapify 和 twitter_bootstrap_rst_directives

這兩個插件讓文章的正文套用上 Bootstrap 的樣式。

bootstrapify 這個插件實現得比較簡單，用 beautifulsoup4 在靜態網頁的結果裏面過濾元素，對 table , img , embed , iframe , video , object 這幾個標籤套用上響應式嵌入對象的類讓他們更美觀。

twitter_bootstrap_rst_directives 這個插件則是增加了幾個 reStructuredText 的行內角色(role) 和指示符(directive) 。它實現的行內角色(role) 包括：用 :kbd: 實現如 Ctrl+C 這樣的鍵盤快捷鍵，用 :code: 嵌入代碼片段，用 :glyph: 嵌入字符圖標。它實現的指示符(directive) 包括： labels 行內標籤， alerts 提示段落， panels 嵌入面板，以及還有一個 media 混排圖標。

對其中的 panel 我改寫了它在文章正文中的樣式，在 lg 或者 xl 的屏幕寬度下，分別用 $\frac{1}{2}$ 和 $\frac{1}{3}$ 大小的嵌入面板，簡單實現和正文文字的圖文混排。

除此以外我還在 twitter_bootstrap_rst_directives 這個插件裏套用它的框架實現了兩個額外的行內角色(role) ，分別是 :ruby: ：通過 html5 的 <ruby> 標籤實現文字上方的注音（firefox下不支持，會使用文字後的括號顯示），以及 :html: ：在行內插入裸(raw) html 標籤（這屬於 Markdown 的基本功能，在 reStructuredText 這邊由於要考慮多種輸出格式於是就比較麻煩了）。這兩個行內角色(role) 的實現代碼在這裏。

2015年2月3日更新

今天又在 twitter_bootstrap_rst_directives 裏增加了兩個行內角色(role) 。一個是 :twi: 用來寫 twitter 用戶的鏈接，比如 @farseerfc ，另一個是 :irc: 用來指向 freenode 的 channel ，比如 #yssyd3 。

2015年2月14日更新

今天增加了 .. friend:: 用來寫好友鏈接，以及 fref 用來引用好友，比如 LQYMGT 這樣。

extract_toc 和 summary

最後是這兩個有點「名不副實」的插件。

reStructuredText 原本就有自動生成目錄(toc) 的功能，用起來也非常簡單，只需要在想要插入目錄的地方寫一行 .. contents:: ，剩下的都由 docutils 自動生成了。只是當然這樣生成的目錄肯定會插入在文章的正文裏，而 extract_toc 這個插件的作用就是簡單地把這個目錄抽取出來，讓模板能在別的地方放置這個目錄。比如我這裏就把目錄放在了一個 panel 裏。

然後 Pelican 也原本就有從文章中抽取總結(summary) 顯示在文章列表的功能。 Pelican 原始的實現似乎是按照文字數抽取前半段，不總是適合作爲總結。於是這個 summary 插件的作用其實是允許在正文中以特殊的註釋的方式標註哪些部分應該被抽出來作爲總結。 summary 這個插件原本的實現只允許抽取一段文字，我又對它的實現做了少許擴充，允許標註多段文字合併起來作爲總結。

2015年1月29日更新

今天在 extract_toc 插件的幫助下，在側邊欄裏放了一個 Bootstrap affix 的目錄，它保持在頁面的右側位置不變，方便導航到文章的各個地方。具體實現方法除了 Bootstrap 3 的 Affix 文檔，還參考了這篇更詳細的說明。

結語

這個博客的配置都可以在 github 上找到，包括用來自動生成整個博客的 Makefile ，由於比較長，這裏就不再貼了。

折騰這個主題前後歷時兩個月，期間學會了不少東西，也算是不錯的收穫吧。現在既然基礎打好了，接下來就要開始多寫博客了。（希望拖延症不會再犯……）

最近發現除了我的博客之外還有一個網站 Kansas Linux Fest fork 了我的主題，不過他們用了我修改的早期版本，還是原本的 Bootstrap 3 和 bootstrap-material-design 樣式。自己草草修改的東西被別人用到果然還是有點小激動呢，以及接下來不能馬馬虎虎地寫 commit 消息了。

[1]	賽65:17「看哪！我造新天新地」啟21:5「我將一切都更新了。」

嘗試一下 Pelican

2012-02-24T17:33:00+09:00

似乎一夜之間所有的極客們都有了自己的 Github主頁和 Octopress 博客。就像所有人在他們的博客中指出的，靜態博客的確比傳統的WordPress方式具有更多優勢。自從看到這些我就一直在想着自己搭一個 Octopress 。

但是似乎 Octopress 不適合我

一上手就被 Octopress的搭建步驟煩到了。 RVM 是什麼？ rbenv 又是什麼？看來 Ruby 社區的快節奏發展已經超過了我的想象，他們似乎需要一套發行版管理器來調和不同版本之間的 Ruby 的兼容性問題。雖然同樣的兼容性問題在 Python 社區也有 [1] ，不過總覺得 Python 至少還沒到需要一個發行版管理器的程度 [2] 。

真正的問題是我手上還沒有一個可以讓我隨便玩的 Linux 環境（真的想要……）。而無論是 RVM 還是 rbenv 似乎都只支持 Unix/Linux/MacOSX 。身爲極客就註定不能用 Windows 麼？（或許是的……）。

剩下的問題就是 Ruby 和 Python 兩大陣營的對立問題了。我不熟悉 Markdown ，相對來說比較喜歡 ReST 。似乎無論哪邊都要依賴 Pygments 作爲代碼着色器，那麼其實 Rubyist 也至少需要安裝 Python 。我傾向於不依賴任何 Ruby 組件，最好沒有 C 擴展的純 Python 實現。

於是我開始在 Github 上找 Python 的靜態博客引擎。 Flask 的作者 mitsuhiko 寫的 rstblog 看起來不錯，不過似乎沒有多少人在用。 Hyde 似乎很完善，不過默認的標記語言是 MarkDown ，又依賴於幾個 Ruby 組建，而且官方網站的設計實在太前衛。最終我看到了 Pelican 。

[1]	比如 Python 2.x 與 3.x 之間看似難以跨越的鴻溝，以及 PyPy 、 CPython 、 Stackless 、 Cython 等各個實現之間的微妙差別。

[2]	是的，我們有 easy_install ，我們有 pip ，不過這些都是包管理器，都是裝好特定的Python實現之後的事情。 Python實現本身還不需要包管理器來管理。 Python 的版本問題基本上也只需要 2to3.py 和 3to2.py 這樣的輕量級轉換器就可以了，你不需要爲了安裝多個軟件而在硬盤裏留下多個不同版本的 Python 。如果爲了引用的穩定性，你可以用 virtualenv ，不過這又是另一回事情了。

那麼就 Pelican 吧

對我而言， Pelican 相比於 Octopress 有幾個好處：

純 Python 實現。這意味着我可以換用任何 Python 解釋器而不必擔心兼容性問題。比如我就換成了 PyPy。

多語言支持。因爲 Pelican 的作者似乎是個法國人。不過這個似乎大部分人不需要…… 我是想儘量把一篇博客寫成三種語言作爲鍛鍊吧。

ReST 。這樣我就可以用 Leo 的 @auto-rst 直接寫 ReST了。簡單方便快捷有效。

不過似乎 Pelican 的關注度不如 Octopress 那麼高，現在一些部分還有細微的問題：

pelican-import 從 WordPress 導入的時候對中文、日文的支持似乎很成問題。

日期格式、時區、字符集、和多語言功能的結合度還不夠。 我在嘗試改善它。

模板還不夠豐富。

插件也不夠多……

希望這麼優秀的工具能夠受到更多關注，以上這些問題都是增加關注度之後很快就能解決的問題。

我的設置 settings.py

安裝 Pelican 很容易，一句話就夠了：

$ pip install pelican

然後把文章寫成ReST的格式，放在`pages`文件夾裏面。(重新)生成只要：

$ pelican -s settings.py

上傳到 Github:

$ git commit -am "Commit message"
$ git push

就這麼簡單。附上我的配置文件：

# -*- coding: utf-8 -*-

TIMEZONE = 'Asia/Tokyo'

DATE_FORMATS = {
    'en':('usa','%a, %d %b %Y'),
    'zh':('chs','%Y-%m-%d, %a'),
    'jp':('jpn','%Y/%m/%d (%a)'),
}
# windows locale: http://msdn.microsoft.com/en-us/library/cdax410z%28VS.71%29.aspx
LOCALE = ['usa', 'chs', 'jpn',        # windows
          'en_US', 'zh_CN', 'ja_JP']  # Unix/Linux
DEFAULT_LANG = 'zh'

SITENAME = 'Farseerfc Blog'
AUTHOR = 'Jiachen Yang'

DISQUS_SITENAME = 'farseerfcgithub'
GITHUB_URL = 'https://github.com/farseerfc'
SITEURL = 'http://farseerfc.github.com'
TAG_FEED  = 'feeds/%s.atom.xml'

SOCIAL = (('twitter', 'http://twitter.com/farseerfc'),
          ('github', 'https://github.com/farseerfc'),
          ('facebook', 'http://www.facebook.com/farseerfc'),
          ('weibo', 'http://weibo.com/farseerfc'),
          ('renren', 'http://www.renren.com/farseer'),
          )


TWITTER_USERNAME = 'farseerfc'

THEME='notmyidea'
CSS_FILE = "wide.css"

DEFAULT_CATEGORY ='Others'
OUTPUT_PATH = '.'
PATH = 'posts'