Pelican Static Site Generator

written in python, ssg, pelican

I'm migrating my blogs on various sites (primarily blogspot) to github pages. I like specifying the content in markdown and having revision control.

The default static site generator on github pages is Jekyll, which is written in Ruby. I tried it out briefly, but decided to go for a generator written in the more familiar Python, so I can hack it if necessary - thus Pelican. Let's explore some of the features. The source for this site is at https://github.com/ryanmckaytx/ryanmckaytx.github.io

Themes#

I pretty quickly found a theme I like, and forked it to switch out the background image, fix a bug, and make a few styling improvements. I also updated it to support the GOOGLE_ANALYTICS config option. I pulled the forked theme into this repo with a git submodule.

Github Pages#

Pelican comes with a github action to publish your site to github pages. But it uses pip and I like to use poetry, primarily for the integrated virtual env and lockfile management. So I tweaked it a bit.

Python-Markdown#

The markdown processor in Pelican is Python-Markdown. It has several officially supported extensions and many third-party extensions.

Table of Contents#

Table of Contents

This is one of the built-in extensions. It adds the permalink to each heading and creates the TOC component. The permalink and TOC look a lot better after some styling.

Code Blocks#

print("Hello Python")

Another built-in extension. Not bad - I wish it had a copy button though.

Mermaid Diagrams#

Support added through the third-party markdown-mermaidjs python-markdown extension.

graph TD; A-->B; A-->C; B-->D; C-->D;

Inline Image#

Bluebonet

Image by Ray Shrewsberry • from Pixabay

Table#

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

It rendered to html correctly. The template styling for tables needed some tweaking.

Import from Blogspot#

Pelican provides the pelican-import tool for importing content from various sources. The exported content from blogspot was about 400KB of xml. After running the tool, all of my blog entries became pages as expected, but there were some unexpected aspects:

  • The comments from the original blog entries each became another page
  • The page content had a lot of embedded html that didn't look good (example)
  • The images were not transferred

So there is a fair amount of cleanup/translation to markdown required.