Working with Pelican

01 December 2017

Following on from last weeks post, this post is going to look at some tips and tricks for working with Pelican.

Updating page names

Pelican produces several pages, such as an archive page, which is available from /archives.html by default. The output filename can be changed by updating the ARCHIVES_SAVE_AS setting in pelicanconf.py:

ARCHIVES_SAVE_AS = 'my_archive.html'

To disable the page being generated, set the variable to an empty string or None:

ARCHIVES_SAVE_AS = None

Custom article URLs

Be default articles are saved to /{slug}.html, where slug is generated from the article title metadata. The slug variable can be overridden in the page source file metadata:

Title: Some Example Page
Slug: example-page

It's also possible to control the URL using the ARTICLE_URL and ARTICLE_SAVE_AS options in pelicanconf.py. For example if you wanted to include the year in article URLs, the following config could be used:

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

Changing the output directory

The Pelican docs have the following info on the output path setting:

OUTPUT_PATH = 'output/'

Where to output the generated files.

Unfortunately if you use the develop_server.sh script this setting will be ignored! This is because the pelican command will explicitly set the output directory with the -o option:

$PELICAN --debug --autoreload -r $INPUTDIR -o $OUTPUTDIR -s $CONFFILE $PELICANOPTS &

The easiest way to get around this is to update OUTPUTDIR in develop_server.sh. Alternatively you could remove the -o option where pelican is called, however the script will still need OUTPUTDIR to be correct so it can switch to the correct directory before running the pelican.server module.

Static content

By default static content will only be taken from the images directory in content/. This can be controlled using the STATIC_PATHS setting:

STATIC_PATHS = ['images', 'downloads']

It's also possible to blacklist directories with STATIC_EXCLUDES, for example:

STATIC_PATHS = ['.']
STATIC_EXCLUDES = ['pages']

Note: since Pelican 3.5 static files can safely be in the same directory as page source files.

Configuring Markdown

Pelican uses the Python markdown module to parse markdown page source files. The MARKDOWN option can be used to control options which are passed to the library. For example if you wanted to excluded the codehilite extension the following config could be used:

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
    },
    'output_format': 'html5',
}

Note: Pelican 3.6.x uses MD_EXTENSIONS, however this has since been deprecated.

Ignoring Git configuration

There is a good chance you will want to version control content generated by Pelican. If you do this, make sure OUTPUT_RETENTION is set to exclude relevant files. For example:

OUTPUT_RETENTION = ['.git', '.gitignore']

This will prevent Pelican purging them unexpectedly!

Date format

People often have different views on date formats. In Pelican date formats can be easily be controlled using the DEFAULT_DATE_FORMAT setting. This setting takes a date format string:

DEFAULT_DATE_FORMAT = '%Y-%m-%d'

It's also possible to support multiple date formats for different locales:

DATE_FORMATS = {
    'en': '%a, %d %b %Y',
    'jp': '%Y-%m-%d(%a)',
}

Note: for more information on date format strings, refer to the Python strftime documentation.

Floating Octothorpe