Pelican is a popular static site generator written in Python. I find it has a better design and provide saner tooling than Hexo. So maybe I'll switch at some point.

HTML directory setup

the ultimate publish dir will be ~/public_html. But for containing the source, create ~/public_html.src, and will use ~/public_html.src/output/ to hold the generated site. So, eventually,

ln -s ~/public_html.src/output ~/public_html

will do.

NOTE: make sure all dirs on ~/public_html.src/output have go+x set.

Pelican setup

Pelican can be installed in isolated way using venv. From inside ~/public_html.src/:

python3 -m venv .ve

# no need to activate the venv:
.ve/bin/python3 -m pip install 'pelican[markdown]'

# initialize the site
.ve/bin/pelican-quickstart

Now a Makefile is created to use pelican for various tasks. However, make for this Makefile requires venv activation. So we create a make wrapper to avoid the ve activation:

$ cat >./make
#!/bin/sh

cd "$( dirname "$0" )"
PATH=./.ve/bin:"$PATH" make "$@"

From now on, all site related tasks can be done via:

./make clean publish

Pelican config

Configs are in pelicanconf.py and publishconf.py. Note that variables can be defined in both, so make sure you only set a varaible at one of them. I recommend setting everything in pelicanconf.py.

Notable config variables:

  • MENUITEMS: defines the "links" displayed in the site's menu bar.

Pelican themes setup

All themes are in https://github.com/getpelican/pelican-themes.

The most basic way to use one is (in ~/public_html.src):

git clone https://github.com/getpelican/pelican-themes.git

Then set the THEME variable (which takes relative path):

THEME = 'pelican-themes/<some_theme>'

Deep customization

Sometimes you need to edit the theme template directly, for example, I want to remove the footer of the "simple" theme, and there's no way to do so with configuration.

For deep customization, we also want to version control the theme files, so it's not desirable to clone getpelican/pelican-themes. Instead, create a themes folder with only the ones you need and customize inside:

mkdir themes

# assume you cloned pelican-themes *outside* of the site repo:
cp -r ~/Downloads/pelican-themes/basic themes/basic

Then make edits to themes/basic and set THEME = 'themes/basic'.

Customizing theme template which is inherited

If the template you want to edit is extended, e.g., basic/templates/base.html has:

{% extends "!simple/base.html" %}

What if it is the simple theme you want to edit? We can make a copy (see note 1) of the simple theme into themes/simple2, and have basic points to it. To do so, we need to set variable:

THEME_TEMPLATES_OVERRIDES = [ 'themes' ]

Then change basic theme's extends directive to:

{% extends "simple2/templates/base.html" %}

Note 1: where do we copy the simple theme, since it comes with pelican itself? You can list all installed themes' locations with:

.ve/bin/pelican-themes -lv