Playing with Pelican (1)

Forewords

I tried a bit Jekyll but I am really not a good Ruby programmer. I looked at the equivalent in Python, and pelican seem to be a good candidate for that.

The advantages:

• I know python
• I know Jinja2 from other projects, especially Django ones
• I know virtually nothing about CSS and Javascript, so to get fancy I need to be able to source knowledge from somewhere

Luckily, Pelican comes with trillions of themes and plugins, and this page is about my own adaptations.

Theme

I started with the theme pelicanyan, itself being an adaptation of lanyon.

The theme itself is pure, does not have many fancy stuff, and has a nice sidebar. Then I started changing many things, to reach the current state. As you can see, I am far from being a native UX guy, and you can appreciate my mistakes (examples of github and bitbucket links).

I copied the theme right into my website repository, as I believe I will make many more changes there and there, and I would like to track those.

Plugins

Table of content

I like having table of contents, especially when the pages become big. There is the plugin extract_toc from the pelican-plugins.

The configuration is done as follow in the pelicanconf.py:

PLUGIN_PATHS = ['plugins']

# for having the TOC
PLUGINS = ['extract_toc']

# adaptation of the extract_toc plugin, requires beautifulsoup
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
    },
    'output_format': 'html5',
    'extensions' : ['toc'] # this is the part added to the default
}

Some explanations:

• I did not find a way to have a better MARKDOWN configuration that inherits from the default one, so I replicated the default and added the necessary extension (see here).
• I like having plugins and themes with me, so I copied the extract_toc into a plugin folder in my repository

After doing all that, each page or article object that is manipulated in the templates of the theme will have a .toc attribute that we may use. For instance, this is how I adapted the page.html template:

{% block content %}
    <h1>{{ page.title }}</h1>
    {% if page.toc %}
    <small class="toc">
      {{ page.toc }}
    </small>
    {% endif %}
{# ... #}

After changing the theme, just adding [TOC]as the first element of pages and posts renders the table of content for the Markdown files.