pelican-theming(1)

Structure

To make your own theme, you must follow the following structure:

├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html         // to display archives
    ├── article.html          // processed for each article
    ├── author.html           // processed for each author
    ├── authors.html          // must list all the authors
    ├── categories.html       // must list all the categories
    ├── category.html         // processed for each category
    ├── index.html            // the index (list all the articles)
    ├── page.html             // processed for each page
    ├── period_archives.html  // to display time-period archives
    ├── tag.html              // processed for each tag
    └── tags.html             // must list all the tags. Can be a tag cloud.

Templates and Variables

The idea is to use a simple syntax that you can embed into your HTML pages. This document describes which templates should exist in a theme, and which variables will be passed to each template at generation time.

All templates will receive the variables defined in your settings file, as long as they are in all-caps. You can access them directly.

Common Variables

All of these settings will be available to all templates.

Sorting

URL wrappers (currently categories, tags, and authors), have comparison methods that allow them to be easily sorted by name:

{% for tag, articles in tags|sort %}

If you want to sort based on different criteria, Jinja's sort command <https://jinja.palletsprojects.com/en/latest/templates/#sort> has a number of options.

Date Formatting

Pelican formats the date according to your settings and locale (DATE_FORMATS/DEFAULT_DATE_FORMAT) and provides a locale_date attribute. On the other hand, the date attribute will be a datetime <https://docs.python.org/3/library/datetime.html#datetime-objects> object. If you need custom formatting for a date different than your settings, use the Jinja filter strftime that comes with Pelican. Usage is same as Python strftime <https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior> format, but the filter will do the right thing and format your date according to the locale given in your settings:

{{ article.date|strftime('%d %B %Y') }}

Checking Loaded Plugins

Pelican provides a plugin_enabled Jinja test for checking if a certain plugin is enabled. This test accepts a plugin name as a string and will return a Boolean. Namespace plugins can be specified by full name (pelican.plugins.plugin_name) or short name (plugin_name). The following example uses the webassets plugin to minify CSS if the plugin is enabled and otherwise falls back to regular CSS:

{% if "webassets" is plugin_enabled %}
    {% assets filters="cssmin", output="css/style.min.css", "css/style.scss" %}
        <link rel="stylesheet" href="{{SITEURL}}/{{ASSET_URL}}">
    {% endassets %}
{% else %}
    <link rel="stylesheet" href="{{SITEURL}}/css/style.css}">
{% endif %}

index.html

This is the home page or index of your blog, generated at index.html.

If pagination is active, subsequent pages will reside in index{number}.html.

author.html

This template will be processed for each of the existing authors, with output generated according to the AUTHOR_SAVE_AS setting (Default: author/{slug}.html). If pagination is active, subsequent pages will by default reside at author/{slug}{number}.html.

category.html

This template will be processed for each of the existing categories, with output generated according to the CATEGORY_SAVE_AS setting (Default: category/{slug}.html). If pagination is active, subsequent pages will by default reside at category/{slug}{number}.html.

article.html

This template will be processed for each article, with output generated according to the ARTICLE_SAVE_AS setting (Default: {slug}.html). The following variables are available when rendering.

Any metadata that you put in the header of the article source file will be available as fields on the article object. The field name will be the same as the name of the metadata field, except in all-lowercase characters.

For example, you could add a field called FacebookImage to your article metadata, as shown below:

Title: I love Python more than music
Date: 2013-11-06 10:06
Tags: personal, python
Category: Tech
Slug: python-je-l-aime-a-mourir
Author: Francis Cabrel
FacebookImage: http://franciscabrel.com/images/pythonlove.png

This new metadata will be made available as article.facebookimage in your article.html template. This would allow you, for example, to specify an image for the Facebook open graph tags that will change for each article:

<meta property="og:image" content="{{ article.facebookimage }}"/>

page.html

This template will be processed for each page, with output generated according to the PAGE_SAVE_AS setting (Default: pages/{slug}.html). The following variables are available when rendering.

tag.html

This template will be processed for each tag, with output generated according to the TAG_SAVE_AS setting (Default: tag/{slug}.html). If pagination is active, subsequent pages will by default reside at tag/{slug}{number}.html.

period_archives.html

This template will be processed for each year of your posts if a path for YEAR_ARCHIVE_SAVE_AS is defined, each month if MONTH_ARCHIVE_SAVE_AS is defined, and each day if DAY_ARCHIVE_SAVE_AS is defined.

You can see an example of how to use period in the "simple" theme period_archives.html template <https://github.com/getpelican/pelican/blob/main/pelican/themes/simple/templates/period_archives.html>.

Listing and Linking to Period Archives

The period_archives variable can be used to generate a list of links to the set of period archives that Pelican generates. As a common variable, it is available for use in any template, so you can implement such an index in a custom direct template, or in a sidebar visible across different site pages.

period_archives is a dict that may contain year, month, and/or day keys, depending on which *_ARCHIVE_SAVE_AS settings are enabled. The corresponding value is a list of dicts, where each dict in turn represents a time period (ordered according to the NEWEST_FIRST_ARCHIVES setting) with the following keys and values:

Here is an example of how period_archives can be used in a template:

<ul>
{% for archive in period_archives.month %}
    <li>
        <a href="{{ SITEURL }}/{{ archive.url }}">
            {{ archive.period | reverse | join(' ') }} ({{ archive.articles|count }})
        </a>
    </li>
{% endfor %}
</ul>

You can change period_archives.month in the for statement to period_archives.year or period_archives.day as appropriate, depending on the time period granularity desired.

Objects

Detail objects attributes that are available and useful in templates. Not all attributes are listed here, this is a selection of attributes considered useful in a template.

Article

The string representation of an Article is the source_path attribute.

Author / Category / Tag

The string representation of those objects is the name attribute.

[1]

for Author object, coming from :authors: or AUTHOR.

Page

The string representation of a Page is the source_path attribute.

Feeds

The feed variables changed in 3.0. Each variable now explicitly lists ATOM or RSS in the name. ATOM is still the default. Old themes will need to be updated. Here is a complete list of the feed variables:

AUTHOR_FEED_ATOM
AUTHOR_FEED_RSS
CATEGORY_FEED_ATOM
CATEGORY_FEED_RSS
FEED_ALL_ATOM
FEED_ALL_RSS
FEED_ATOM
FEED_RSS
TAG_FEED_ATOM
TAG_FEED_RSS
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS

Inheritance

Since version 3.0, Pelican supports inheritance from the simple theme, so you can re-use the simple theme templates in your own themes.

If one of the mandatory files in the templates/ directory of your theme is missing, it will be replaced by the matching template from the simple theme. So if the HTML structure of a template in the simple theme is right for you, you don't have to write a new template from scratch.

You can also extend templates from the simple theme in your own themes by using the {% extends %} directive as in the following example:

{% extends "!simple/index.html" %}   <!-- extends the ``index.html`` template from the ``simple`` theme -->
{% extends "index.html" %}   <!-- "regular" extending -->

Example

With this system, it is possible to create a theme with just one file.

main.css

The file is static/css/main.css (the default CSS_FILE):

body {
    font-family : monospace ;
    font-size : 100% ;
    background-color : white ;
    color : #111 ;
    width : 80% ;
    min-width : 400px ;
    min-height : 200px ;
    padding : 1em ;
    margin : 5% 10% ;
    border : thin solid gray ;
    border-radius : 5px ;
    display : block ;
}
a:link    { color : blue ; text-decoration : none ;      }
a:hover   { color : blue ; text-decoration : underline ; }
a:visited { color : blue ;                               }
h1 a { color : inherit !important }
h2 a { color : inherit !important }
h3 a { color : inherit !important }
h4 a { color : inherit !important }
h5 a { color : inherit !important }
h6 a { color : inherit !important }
pre {
    margin : 2em 1em 2em 4em ;
}
#menu li {
    display : inline ;
}
#post-list {
    margin-bottom : 1em ;
    margin-top : 1em ;
}

Custom templates

If you want to customise the templates as well, you can extend them. For example, to add a custom footer, create a templates/base.html:

{% extends "!simple/base.html" %}
{% block footer %}
    <p>Custom footer</p>
{{ super() }}
{% endblock %}

This file will be extended by all the other templates, so the custom footer will appear on all pages.