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'