Installing Pelican

Today I migrated this blog to use Pelican, a python-based static site generator.

On the whole, the setup was pretty easy, but I hit a few snags setting up the theme.

This is how I installed on a Mac

First, get a clean python environment

brew install pyenv pyenv-virtualenv
pyenv install 3.7.4
pyenv virtualenv 3.7.4 blog
pyenv activate blog

Then install pelican

pip install pelican pelican-themes

And optional dependencies

pip install Markdown typogrify

Then run the quickstart, which will setup your config and deployment after you answer a few questions about the desired configuration

pelican-quickstart

So far, so good. This is where I started to hit some conflicting information.

Next, create some content, for example, my root folder is called blog, so I created a file called blog/content/my-article.md, with contents:

Title: My Article
Date: 2020-11-02
Category: Test

This is my article content.. etc..

And then publish with the following command

pelican content

This combines the individual articles in your "content" folder with the theme/template code, to generate static HTML for each page for the site.

Then you can start a webserver to check the results

pelican -l

Note that the docs suggest using python -m pelican-server, but this appears to be deprecated in favor of pelican -l

And the site should be available at http://127.0.0.1:8000 for testing.

Next, I wanted to change the date format to Y-m-d, which was pretty easy.

I edited blog/pelicanconf.py and set:

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

The list of all settings is available here: https://docs.getpelican.com/en/stable/settings.html

Finally, I wanted to change the theme. This is super easy, but took me way too long.

First, make a directory for downloaded themes

cd blog
mkdir themes

Next, download your target theme. A large list of themes is available on the Pelican Themes github repo. I downloaded the pelican-hyde theme.

git clone https://github.com/jvanz/pelican-hyde

Then, edit blog/pelicanconf.py and set (or add):

THEME = 'themes/pelican-hyde'

Be Careful: pelicanconf.py vs publishconf.py

There is a difference between pelicanconf.py and publishconf.py. This is best described on StackOverflow. But basically, pelicanconf.py is for most of what you'll want to change during local development, and publishconf.py is for production-only settings.

When you run pelican content, it is only looking at the local development settings found in pelicanconf.py. So if you try to change your theme by editing publishconf.py, it won't work locally. You CAN run make publish and that will evaulate both files. But it seems the author's intention was to keep them separate and that pelican content should be used locally.

I did not realize this for over an hour.