Moving the Blog to Hugo

This blog has been running on Pelican since 2011. I’ve been pretty happy with it, even contributing AsciiDoc support upstream. But lately I’ve been feeling like it’s time for a change. I’d heard good things about Hugo from friends, and even though my first attempts with it were frustrating (thanks to their docs pointing to content/posts/ instead of content/post/) I decided to give it another try after my attempts to add a Mastodon social icon to the mg theme for Pelican failed. It uses Font-Awesome for its icons, and I couldn’t untangle how to extend it or update to a newer version so I used that as a good reason to make a complete change.

My content under Pelican was a mixture of Restructured Text, AsciiDoc, and Markdown. Hugo supports all 3 of these with varying degrees of success, Markdown having the best support. Restructured Text is passed through rst2html, and AsciiDoc through asciidoc or asciidoctor. I had trouble getting AsciiDoc to work so I decided to change my AsciiDoc pages to Markdown.

I had a few things that I needed to make sure were working before I made the actual switch:

  • Aliases for the old urls needed to be redirected to the new location
  • Add new social icons easily
  • Syntax hilighting for code and configuration snippets
  • Search using DuckDuckGo

URL Aliases

The Pelican content used what Hugo calls ugly URLs for its paths. Switching on this option in Hugo’s config.toml did produce page names ending in .html but they were all under /post/ which doesn’t help. Luckily Hugo has the Aliases option that can be added to each post’s front matter to redirect the old URLs to the new Hugo location.

---
Aliases: [/url/for/old-ugly-post.html]
---

This will redirect requests to the new location so that links to your content won’t end up broken. This solved the most important consideration I had in changing to Hugo.

Adding new social icons

I’ve been fairly active (for me) on Mastodon lately, so I wanted to make sure I could add a link to it with a nice looking logo. The theme I chose, mainroad , supports a variety of social networks, but not Mastodon or Keybase.io . The html is in the social.html template and uses SVG for the icons. I Added the SVG from Mastodon to the theme by making a new div and pasting in the SVG. See this commit for the changes.

I also changed the Twitter icon color to its official blue color.

And I added a monochrome Keybase.io icon that I borrowed from Font Awesome .

Syntax Hilighting

Hugo has excellent support for hilighting in Markdown content, if the theme you are using supports it, you just need to turn it on in the config.toml file:

pygmentsCodeFences = true
pygmentsUseClasses = true

It isn’t actually using Pygments for Markdown, but it uses the same configuration options . A quirk here is that the theme you are using needs to support it, which Mainroad doesn’t. So I spent some time cursing things until I realized that all I needed to do was provide a syntax.css file and including that file in the headers. You can see the commit here . I borrowed the syntax.css from another Hugo theme that advertised syntax hilighting support.

But I still wasn’t getting any hilighting for Restructured Text. After looking at the generated html for the site I realized the classes that rst2html uses are different from the ones in the syntax.css file. You can generate them using pygmentize but the class names are still wrong, it uses the short names. I stumbled across this script on stackoverflow.com that generates the files using the short and long classes, but includes a .hilight prefix. A quick search/replace with vim took care of that, and I had a pygments compatible syntax hilighting css file to add to the Mainroad theme . Now hilighting for Restructured Text works!

Search Using DuckDuckGo

The Mainroad theme uses Google for its search widget . I used the DuckDuckGo Search Box generator to create an iframe that uses https plus redirects, and fits inside the space available (that was the hardest part). You can see the commit here .

Converting AsciiDoc to Markdown

For all of my Pelican pages I had to edit the top of the page to convert the page tags to yaml so that Hugo would recognize things like the title, date, etc.

---
Title: Moving the Blog to Hugo
Date: 2018-12-21 17:41:00
Tags: [Hugo, Pelican, Blog]
Slug: moving-the-blog-to-hugo
Aliases: [/moving-the-blog-to-hugo.html]
---

Hugo uses the filename as the slug if one isn’t provided, and it is sensitive about the date format, if it doesn’t match the format defined in the dateformat option of config.toml it assumes the post is old. AsciiDoc uses backtick surrounded urls that needed to be changed, easy to convert using a vim substitution regex s/`\(.*\)<\(.*\)>`_/[\1](\2)/. Bold, italics, and fixed-width font was changed with simple search and replace.

Thumbnails

One other thing I changed in the Mainroad theme was the Thumbnail support. I wanted any Thumbnail that I set to show up on the list of posts, but not at the top of the post page. My thumbnails are always images included in other parts of the post, so having them appear twice looks weird. I removed that bit from the template for posts in this commit .

I’m really happy with how things went. Hugo is fast, even with a bunch of Restructured Text content, and the template system it is using has been easy to understand and make small tweaks to without too much trouble. The biggest problem was syntax hiligting support – I’m not sure why a theme would leave that out since it’s a really simple change to include it. It took me a whole day to do the conversion, but that has been time well spent.