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
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
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
--- 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.
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
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
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
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
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.
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.