Migrating from Octopress to Pelican

YAML Front Matter

Octopress uses YAML front matter for post meta data, such as title, date, tags, etc. Pelican can recognize most of them but tags and category. More specifically,

1. In Octopress, you can put a post in multiple categories using the categories attribute. But in Pelican, one post can only in one category using the category attribute. This may cause trouble if you had some post in multiple categories in Octopress.
2. Pelican can not recognize the YAML front matter for tags, which is very similar to a JSON array. For example, in Octopress, it's tags: ["tag1", "tag2"]. In Pelican, it's tags: tag1; tag2.

I fixed the first one by substituting all categories with category. Then I tried to manually convert the YAML style array to Pelican style array using sed, which failed miserably.

Then I found the md-metayaml Pelican plugin, which was exactly what I needed. Just add md-metayaml to your PLUGINS and boom, Pelican can now recognize YAML front matter!

Liquid Tags

Octopress uses Liquid Tags for multimedia resources, such as images, videos, etc. Similar to YAML, there is also a liquid-tags plugin for Pelican. I mostly use the img tag, so I just added liqued_tags.img to the PLUGINS. You can add others as well, such as youtube, video.

However, there is one tags that I used before that is missing in liquid-tags plugin---blockquote. Fortunately, I only used this tag in one post and I happily convert it using the standard Markdown block quote syntax.

Summary Text

By default, Pelican uses a fixed number of words as the post summary. I prefer the way that Octopress handles summary: explicitly use a excerpt separator (<!-- more -->) to control which part goes to the post summary (typically first paragraph).

Again, there is this summary plugin that does exactly as mentioned above. Just put summary in PLUGINS and set SUMMARY_END_MARKER to be <!-- more -->.

URL Pattern

This is probably just me: the URL pattern on this site is actually inherited from the old days when I was using WordPress. Basically, the post URL is something like /2015/10/11/title-slug/index.html, which corresponds to 2015-10-11-title-slug.markdown file in Octopress.

First, we need to tell Pelican to obtain URL slug from the file name:

1

FILENAME_METADATA = '(?P<date>\d{4}-\d{2}-\d{2})-(?P<slug>.*)'

Then we set the article URL pattern:

1
2

ARTICLE_URL = '{date:%Y}/{date:%m}/{date:%d}/{slug}/'
ARTICLE_SAVE_AS = '{date:%Y}/{date:%m}/{date:%d}/{slug}/index.html'