This Blog Is Now a Pythonic Pelican-Powered Publication
I started this blog in 2014 using the popular Jekyll. Whilst it served me well, I’ve wanted to migrate to a Python-based tool for a while now, for a few reasons:
Jekyll is written in Ruby, and I don’t really know Ruby. For extensions I have had to crib code from others and blunder through things, which has prevented me from adding some features that I wanted to.
Equally, my unfamiliarity with Ruby means a lot of overhead for maintaining its installation, updating gems (packages), and knowing the commands, just for this one project.
Jekyll is Markdown-based, whilst I’d now prefer to write in reStructuredText (rST). I have familiarity with rST as it is the lingua franca for Python project documentation, and think it is a better format (even in 2021!).
Because rST is semantic, it is ideal for projects with multiple output formats. This is why I used it for my book, which I output as a PDF, ePub, and AZW for Kindle. Using rST for my blog will make it easier to copy content between the blog, my current book, and any future books.
Jekyll does have an extension to support reStructuredText, but it’s fairly limited. This is because the underlying tool, docutils, is written in Python. Using a Python-based site generator means easily extending docutils.
I started investigating a migration a couple weeks ago, trying various ideas such as using Sphinx or writing my own docutils-based static site generator. After finding Pelican would fit my needs perfectly, I picked it and started a migration in earnest on Saturday the 4th September. I didn’t work full time on this, but it did take several days’ worth of effort, which culminated this morning with a deployment of the new site.
The migration involved starting a new Pelican site, copying over my existing templates, tweaking Pelican settings, and importing my old posts. Pelican supports both Markdown and rST, but rather than leave my 205(!) old posts in Markdown, I wanted to migrate them too for consistency. I’m glad I did, as the extra tooling I’ve added allowed me to make numerous small improvements. I migrated them with a combination of pandoc, Python, regular expressions, and manual persistence working through each post in turn.
Site Improvements
Here are some of the improvements I made during the migration:
- Hovering over a sub-heading will reveal a pilcrow (¶) linked to the heading’s anchor. This lets you copy a link to that specific point in a post.
- There are now archive pages for year, month, and day. I haven’t linked to them yet, so to access you’ll need to visit a post page and then edit the URL to cut off the slug (and maybe month or day). For example, here’s the 2021 Archive.
- There’s now a page listing all tags, with post counts.
- Every tag has an associated atom feed, rather than just a few of them. So if you’re only interested in a particular topic, you can subscribe to that. For example, subscribe to
https://adamj.eu/tech/atom-mypy.xmlfor Mypy-related posts. - All Python code samples in posts are automatically formatted with Black, thanks to blacken-docs. This also allowed me to catch and many small bugs in code samples.
Fin
Hope you enjoy the new site. If you are thinking of starting a blog yourself: P-P-Pick up a pelican*!
—Adam
Read my book Boost Your Git DX to Git better.
One summary email a week, no spam, I pinky promise.
Tags: writing