How to from Jekyll jump into Pelican

2013-12-19T10:42:00+08:00

[TOC]

如何从 Jekyll 转进入 Pelican

简述静态网站从 Jekyll 环境中迁移为纯 Python Pelican...

为毛

社区在发展, 原先的蠎周刊,为方便,使用了 gitcafe 内置的 Jekyll 服务, 所以,其实在使用 Ruby 自动编译和发布.

总是感觉不够纯粹 Pythonic ...

故而, 下决心完成迁移

整体

忽然发现,俺感觉很直觉的事儿,也写了文档, 但是,其它人真正首次上手全然一头雾水...

所以学习学习再学习 - xiaolai 提出的,俺实在无法同意更多..

这是最难的知识结构——它往往看起来跟线性结构没什么区别，但，最终令人迷惑，甚至懊恼。用最直白的话来描述，就是：

初级的知识需要对高级知识深入了解才能真正深入了解

——你看看这句话多拗口就多少有点概念了。

所以,还是按照 easy 模式来, 先简单的说,再往死里说折腾的技术细节...

已知条件

User, Organization and Project Pages

github 的所谓 pages 服务的本质:

云端的 Jekell 服务
对约定的仓库,感知变化时,就尝试进行编译
并自动完成发布(现在是到 github.io)

这里的约定仓库,只有两种情况:

用户/组织:
- 比如, 注册成的用户/组织为 https://github.com/foo
- 则, github 尝试进行 pages 发布的仓库为:
- https://github.com/foo/foo.github.io
- 发布到: https://foo.github.io
项目
- 任意一个项目仓库,比如, https://github.com/foo/foobar
- 则, githuba 支持自动对此仓库的 gh-pages 分支进行 pages 编译
- 而发布为: https://foo.github.io/foobar

Pelican行为

Pelican 呢其实也只是 Python 世界中大堆静态网站发布工具中的一个, 为毛选中这个? 只是因为 42分钟里,大妈将其折腾起来了, 而且官方的文档/案例/样式,的确足够丰富, 给人信心...

而其本身对网站的约定非常简单:

配置好 pelicanconf.py
在 content 目录中写作
一键命令编译完成静态网络的生成,组织到 output

所以?方案!

基于以上的整体理解, 就可以决策怎么基于 github 的 pages 服务, 来进行免费的网站发布了;

目测也就两招:

在用户/组织的 pages 仓库中直接部署 Pelican 工程
- 只是要在根目录部署一个自动跳转到 output 子目录的 index.html 页面
- 以便发布后可以略过根目录来访问编译结果的内容
- 发布成 https://foo.github.io/output
用两个仓库, 将用户/组织的 pages 仓库部署为 output 子目录
- 这样就能自动发布为 https://foo.github.io

很明显,第二种逼格较髙,所以,就这样办了!

宏观流程

首次建立本地撰写环境:
1. 安装好 Pelican
2. 分别clone 出两个仓库:
  - qpython-android.pelican
  - qpython-android.github.io
3. 先在 qpython-android.pelican 中测试确认好 pelical 工程可用,并尝试编译
4. 一切正确的话,将 qpython-android.github.io 复制覆盖为 qpython-android.pelican/output
以后,日常的维护就再也不需要 qpython-android.github.io 了!
1. 进入 qpython-android.pelican/content 创建/增补/修订文章
2. 回到 qpython-android.pelican 执行 fab build
3. 本地到 output 打开对应页面检查效果
4. 还是在 qpython-android.pelican 执行 fab pub2hub
  - 完成对 qpython-android.github.io 仓库实际的 push
  - 即, 发布成网站: http://qpython-android.github.io
5. 最后,在 qpython-android.pelican 进行正常的 git add->ci->pu
  - 对文章源文本完成到 qpython-android.pelican 仓库的提交

收功!

细节

然后, 再分享俺的折腾过程...

过程

整体上,其实就三步:

选择一个 theme ,完成本地 demo 整明白怎么使用 Pelican
将原先 Jekyll 格式的文章声明部分文本, 批量转化为 Pelican 的
改进发布流程,自动化

theme

综合对比了官网收集的一堆样式,选择了 DandyDev 的,根据说明,立即就完成了编译,本地检阅 ;-)

fab

果断使用 fabric 进行自动化处理!

参考: fabfile.py
定制了 pub2cafe 完成自动化发布

因为 gitcafe 只有用户同名-pages 服务,所以,对于当前 蠎周刊 的 Pelican 工程, 用两个仓库,配合完成:

https://github.com/qpython-android/qpython-android.pelican.git
    +- ..
    +- pelicanconf.py   主配置文件
    +- content          内容目录  
    +- output           编译输出目录
    |    `- https://github.com/qpython-android/qpython-android.github.io.git 
    |                          |
    |                          \-- 即合法的
    +- .gitignore       配置忽略 output 目录
    +- ...

这样一来,目录,就不用进入 output 目录进行 git 操作了平时的发布流程就是:

在 content 目录对应分类子目录中创建 *.md 文本,组织文章
fab build 完成编译,本地检阅文章效果
git add . && git ci && git pu 将增补提交
fab pub2cafe 自动完成进入 output 后的一系列 git 操作

对应的配置中:

#DELETE_OUTPUT_DIRECTORY = True

就绝对不能打开注释不然 output 目录清除,就没有了 .git 也就无法发布了...

坑

整个过程中,遇到没有找到文档的小麻烦,自个儿解决了的....

DISQUS

果断遇到了 DISQUS 配置了,不生效的问题,上下折腾, 才发现很多人都遇到了这个问题, 追踪到代码:

//... pelican-themes/pelican-bootstrap3/templates/includes/comments.html
//...
var disqus_shortname = '{{ DISQUS_SITENAME }}'; // required: replace example with your forum shortname
var disqus_identifier = '{{ article.slug }}';
var disqus_url = '{{ SITEURL }}/{{ article.url }}';

才发现 SITEURL 的配置是决定性的, 一定要同 DISQUS 申请时的一致; 本地编译后, 看一眼源代码,就知道是否靠谱了...

CATEGORY_FEED_ATOM

一时手賎,打开了:

CATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'

结果,发现不能在模板里简单的完成分类子 RSS 的链接!

    <i class="icon-th icon-large"></i>Categories</h4></li>
{% for cat, null in categories %}
    <li class="list-group-item">
        <a href="{{ SITEURL }}/{{ cat.url }}">
            <i class="icon-folder-open icon-large"></i>{{ cat }}
        </a>
        <a href="{{ SITEURL }}/feeds/{{ cat }}.atom.xml">
            <i class="icon-rss-sign"></i>
        </a>
    </li>
{% endfor %}

因为这儿的 {{ cat }} 是分类的名称,可能包含大小写字母, 而配置指导下生成的 RSS 文件是全小写的...

纠结了一会儿,也没有查到对应的文档,突然想到各种内置对象都有的 sulg 属性!

于是就猜对了... 参考: includes/sidebar.html#22

author

原样式作者因为是个人网站,所以,无所谓 Author 的信息, 但是,作为社区用共笔环境,就必须有所体现, 在 includes / article_info.html 先打开作者的属性输出,

然后,从别的 theme 工程中抄一个模板: author.html

即好!

参考:

Changelog

160401 ZoomQuiet 迁移发布到 github as gh_pages
140127 ZoomQuiet 增补宏观理解
140120 ZoomQuiet 复制到 QPython 的 Pelican 工程
131219 ZoomQuiet 为 CPyUG/weekly - GitCafe 创建

蠎周刊 - Chaos