Converting from Pelican to Hugo

I have been using the Pelican static site generator for more than 5 years. It has served me quite well. Recently I decided to convert the entire site to use Hugo instead to gain some experience with other static site generators. I picked Hugo in particular because I have been gaining experience with the Go programming langauge for the last 4 years and, since Hugo is written in Go, the experience with Go might be helpful.

Initial Impressions

So far, converting the Pelican web site to Hugo has been mostly straight forward. The front matter for each page was mostly a one-to-one translation. I decided to use the YAML style for the front matter since YAML is so familiar, though, any of the three front-matter formats would have been fine and relatively familiar.

For example, the following front matter from Pelican:

Title: Recovering Fedora 30 after a Power Outage During an Update
Date: 2020-02-02
Modified: 2020-02-02
Tags: Linux, Fedora, LUKS, Xfce
Slug: fedora-update-recovery
Authors: Paul Graham
Summary: Find out how I recovered a Fedora 30 system that experienced a power outage during an update.

became:

---
title: Recovering Fedora 30 after a Power Outage During an Update
date: 2020-02-02
lastmod: 2020-02-02
tags: 
- Linux
- Fedora
- LUKS
- Xfce
slug: fedora-update-recovery
authors:
- Paul Graham
summary: Find out how I recovered a Fedora 30 system that experienced a power outage during an update.
---

I like the fact that the front matter is clearly delimited, though, I don’t know that it matters very much. Also, I have updated to the latest Pelican, so there might have been some changes in how Pelican handles the front matter.

Understanding how Hugo expects content to be organized was also relatively straightforward, though, it has really taken some practical experience to really understand several of the concepts. In the end, the organization of the files is quite similar to what I used for Pelican. Some of the differences include:

  • Pelican was a little more automatic in how it generated the menus in the navigation bar, but Hugo provides a user a fair amount of control over the menus, which can be useful.
  • Of course, how the two systems handle references to other pages differs. In Pelican, I was using references like: {filename}/blog/Technology/fedora-on-dell-precision-5520.md. In Hugo, I am using relative references as follows: {{< relref "fedora-on-dell-precision-5520.md" >}}, so the path can be relative to the location of the Markdown file.
  • Referring to static images is a little cleaner in Hugo. In Pelican, I used the following to refer to an image: {static}/images/musescore-logo-transbg-m.png. For Hugo, I can simply use /images/musescore-logo-transbg-m.png instead.
  • Hugo allows you to easily provide a way to modify the front matter for list templates by creating a _index.md in the directory hierarchy. This way you can provide a description for a section, change the featured image for the list page, etc. I am not familiar with how you would do that with Pelican, though, I never tried to override those settings for a given category of articles.
  • Of course, the templating languages are different. Pelican uses Jinja while Hugo uses the HTML templating facilities from Go.
  • Likewise there are differences in the configuration files, but nothing significant so far.
  • Since Pelican and Hugo are both packaged for Fedora, the installation is not terribly different, though, it seems like I had to hand-satisfy some of the Pelican dependencies when they were not required, of course. Hugo seems a little more self-contained.
  • The paths generated for content is also a little different. Pelican provides a more flattened hierarchy for the content while the content generated from Hugo follows the hierarchy of the original source. By default, in Hugo, it seems like individual pages get generated as index.html files placed in directories following the original file system hierarchy. So references to posts and pages seems to be references to the directories with the directories containing the index.html files rather than pointing to .html files themselves. Hugo does allow for page bundles, which means that that content for individual posts can be more self-contained as opposed to having the images in one location and the HTML in another. Again, probably not a big issue in general, but there are a lot of subtle differences.

To reproduce the photo gallery plugin features that I used with Pelican, I found the following “shortcode” implementation that seems to function reasonably: Hugo Easy Gallery.

MathJax Support

To add MathJax support to Hugo, I followed the primary answer provided on this StackOverflow question. Effectively, you configure Hugo to put the following JavaScript in the <head> tags of all of the pages:

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

by placing that code in layouts/partials/head-additions.html for your Hugo site.

I think this MathJax solution along with the photo gallery solution provide an interesting glimpse into the configurability and composability of Hugo features without having to deeply modify themes.

AsciiDoc Support

I really like AsciiDoc as a markup language. It was originally supported by a Python-based tool to convert from AsciiDoc to other formats, like HTML, PDF, DocBook, etc., but now the Python implementation has been discontinued and there are several other tools for converting AsciiDoc to other formats. Many of them are based on AsciiDoctor, which was originally written in Ruby, but there are now several derivatives implemented with other languages.

To use AsciiDoctor with Hugo, I had to add the following to the config.toml:

[security]
    [security.exec]
    allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$', '^asciidoctor$']

This effectively allows Hugo to run the asciidoctor processor for processing AsciiDoc files.

Concluding Comments

In any case, so far so good with the conversion. I will likely comment on this more as I develop the site further.