Setting up Pelican for publishing.

Pelican is a static site generator written in Python. The coolest thing about it is the support for Markdown, Pygments, themes and of course Python.

Install

To start using Pelican it you have to clone it or install it from PyPI. You also might need to install some other package dependencies.

pip install pelican
pip install bs4
pip install i18n
pip install webassets
pip install markdown

Pelican comes with no plugins and two very basic themes, so you have to clone the needed ones to some local directory. I have cloned the whole official plugins and themes repositories, since I wanted to experiment with different options.

To ease things, you can choose to clone them directly into the themes and plugins directories of the Pelican package directory \site-packages\pelican or just setup the directories in the configuration file later.

An aggregated collection of themes and screenshots can be found at www.pelicanthemes.com. Some of the themes are nice and documented and some, well, are not at all. I obviously decided to go with the pelican-bootstrap3 theme.

Configure

The next thing to do is to create a configuration file for Pelican in the root directory of your working space. There are many common setting, but the configuration heavily depends on the template you choose to use.

Each theme can have its own set of features and configuration names. I strongly suggest you to lookup the templates directory of each theme where you can get clues what you can do with it and even change it as you need.

I think the most important are the URL links to your articles and pages, since you do not want to break any possible references to your blog when you decide to change the site layout or whatever. This should always be consistent.

ARTICLE_URL = "article/{date:%Y}/{slug}"
ARTICLE_SAVE_AS = "article/{date:%Y}/{slug}/index.html"
PAGE_URL = "page/{slug}"
PAGE_SAVE_AS = "page/{slug}/index.html"

Here you can also select any color-schemes provided byt the theme, the Pygment style and many other things. Just go ahead and experiment, it is not that hard to get it working.

It is also a good idea to distinguish some settings for "draft" and "release" stages of your site using a PUBLISH variable and conditions, for example not to use Google Analytics and Disqus when changing and browsing the site locally.

Write

Writing a blog using Pelican and Markdown is really easy. Just make sure you explore all the possible headers for your articles and the support for them in the Pelican template used, there may be some custom ones.

Title: Setting up Pelican for publishing.
Date: 2017-03-24 13:00
Category: Engineering
Tags: Publishing, Pelican, Python
Author: Ladislav Malacky-Bakay
Summary: Getting started with Pelican may be a breeze or not.

Build

Now you can build your HTML output.. well, not quite. You may encounter some issues, like I have.

CRITICAL: UndefinedError: '_' is undefined
CRITICAL: UndefinedError: 'gettext' is undefined

The first one is quite easy to fix. The JINJA template engine needs to know about the i18n extension, so you just define it in the configuration file.

JINJA_ENVIRONMENT = { "extensions" : [ "jinja2.ext.i18n"] }

The second one can be a bit tricky as described in this issue. One easy fix though is just to include the i18n_subsites Pelican plugin in the configuration file.

PLUGINS = [ "i18n_subsites" ]
PLUGIN_PATHS = [ "\site-packages\pelican\plugins" ]

Another possible fix is to use a hack and edit the \site-packages\pelican\generators.py file directly like this.

# add this after other imports
import gettext
# add this to Generator.__init__ after self.env
self.env.install_gettext_translations( gettext )

Et voilà, now you are ready to write, build and publish with Pelican!