Configuration

Turbopelican eliminates the need to use two scripts (pelicanconf.py and publishconf.py) for configuring Pelican by providing a pelicanconf.py script which will correctly load the appropriate configuration depending on your situation. As a result, you will want to modify your turbopelican.toml configuration file. You do not need to modify pelicanconf.py.

Using TOML to configure Pelican

Pelican has a number of settings which can be changed according to your need. Turbopelican allows you to define them in turbopelican.toml instead. By default it should look something like this:

[pelican]
author = "Elliot Simpson"
sitename = "MySite"

timezone  = "Pacific/Auckland"

default_lang = "en"

path = "content"

default_pagination = false

theme = "themes/plain-theme"

article_paths = []
page_paths = [""]
page_save_as = "{slug}.html"

static_paths = ["static", "images"]

index_save_as = ""

author_feed_atom = "None"
author_feed_rss = "None"
category_feed_atom = "None"
feed_all_atom = "None"
translation_feed_atom = "None"

[[pelican.extra_path_metadata]]
origin = "static/favicon.ico"
path = "favicon.ico"

[[pelican.extra_path_metadata]]
origin = "images/logo.svg"
path = "logo.svg"

[publish]
site_url = "https://turbopelican.github.io"
relative_urls = false
feed_all_atom = "feeds/all.atom.xml"
category_feed_atom = "feeds/{slug}.atom.xml"
delete_output_directory = true

The simple rule is that settings under [pelican] configure Pelican during development, while settings under [publish] configure Pelican during publication. Because most of your settings will be mostly the same in both contexts, settings not defined in [publish] will fallback to those defined in [pelican] if possible.

The name of all settings should be the same as those in Pelican, except lowercase. The only exception is SITEURL which is written within the TOML as site_url with an underscore.

Where Pelican expects tuples or lists, use arrays. Where Pelican expects dictionaries, use tables. There is one exception to this. The EXTRA_PATH_METADATA setting in Pelican needs to be a dictionary, for example:

EXTRA_PATH_METADATA = {
    "static/favicon.ico": {"path": "favicon.ico"},
    "images/logo.svg": {"path": "logo.svg"},
}

To achieve this in turbopelican.toml, the keys of EXTRA_PATH_METADATA are flattened into the values with the key "origin":

[[pelican.extra_path_metadata]]
origin = "static/favicon.ico"
path = "favicon.ico"

[[pelican.extra_path_metadata]]
origin = "images/logo.svg"
path = "logo.svg"

Refer to the Pelican documentation for what each setting does.

Special values

The pelicanconf.py file needs to be capable of containing settings with values of None. In some cases, certain settings will need to contain functions. TOML does not natively contain either of these concepts.

None values

By default, Turbopelican will swap any "None" string values for None. If this causes an issue, it is possible to change the sentinel value (meta.null_sentinel) to something like -1:

[meta]
null_sentinel = -1

[pelican]
analytics = -1 # Becomes `None`

Or "TurboPelicanNull" like so:

[meta]
null_sentinel = "TurboPelicanNull"

[pelican]
author = "TurboPelicanNull" # Becomes `None`

Functions

Breaking the strictest conventions of configuration, Pelican can be configured with functions. Though TOML has no native concept of functions, Turbopelican lets you parse strings as functions like so:

[[meta.module_prefix]]
prefix = "@urlencode:"
module_name = "custom_filter"

[pelican]
jinja_filters = {urlencode = "@urlencode:urlencode_filter"}

This is equivalent to the following Python:

from custom_filter import urlencode_filter


JINJA_FILTERS = {
    "urlencode": urlencode_filter
}

Whenever a prefix value is found beneath [pelican] or [publish], the subsequent string is treated as the name of the function to be imported from the module with the specified module_name. Note that this means the module should be found from the PYTHONPATH.