Migrating from Jekyll to Hugo

Project Profile#

• Difficulty: Medium (3/5)
• Cost: €0
• Time: ~20h

In this project, I describe my migration from Jekyll using the Minimal Mistakes↗ theme to Hugo, utilizing a heavily modified Terminal theme↗.

Why switch at all?#

For quite some time, I hadn’t been fully satisfied with building my website using Jekyll. The trigger for the switch was a day when I suddenly couldn’t build the site locally due to a compatibility issue in Ruby. Standard commands like bundle update --conservative or bundle install didn’t help. Even manually installing the problematic packages using commands like gem install commonmarker-0.23.12 or gem install posix-spawn -v 0.3.15 -- --with-cflags="-Wno-incompatible-function-pointer-types" failed to resolve the problem.

Updating Ruby and Jekyll themselves didn’t work either. Besides, build times with Jekyll had become quite long. Since moving the site from GitHub Pages to my own server, I am no longer tied to Jekyll, making a switch more attractive.

This no-build-locally problem was just the final nudge that made me begin this laborious task. I hate it when technology doesn’t do what I want - even though I admit that often times, I am the root cause for that myself.

Further difficulties with Jekyll#

• CI/CD: My deployment pipeline had failed months ago due to similar errors, forcing me to revert to an older version of Jekyll. This increases technical debt and the attack surface of my GitHub Actions. I would have to look for a well-maintained container solution from another provider. Searching for and setting one up would require additional time.
• RSS feed: I wanted to provide an RSS feed for my website. However, my experiments with Jekyll showed that only “posts” were included, not “announcements.” I wanted to fix this.
• Image formats: Jekyll normally generates cover images (thumbnails) for posts within the RSS feed. Unfortunately, this stopped working after I switched from .jpg to the more space-efficient .avif format. Despite several attempts, I couldn’t get a solution approved through the pull request review process.
• Icons: The theme I was using relies on Font Awesome to display icons and is quite large overall for a static website. Since I didn’t want to load assets from external sources, I stored the library locally. My plan was to select only the icons I actually needed and delete the rest. With the switch to Hugo, this is no longer necessary.

Opportunities#

I expect Hugo to deliver faster build times, a simplified CI/CD process (without the need to install Bundler, Ruby, etc.), and a resolution to the difficulties described above. Hugo’s approach to dependency and package management differs fundamentally from Jekyll’s: additional content is integrated via Git Submodules↗, and dependency management relies on Go modules↗ rather than a Gemfile↗.

The migration tool#

The folder structures for content differ significantly between Jekyll and Hugo. I am therefore using an import tool↗ included with Hugo, which correctly imports at least the articles located under /posts. However, specific content such as overview pages (/tags, /pages/error, /pages/legal), and pages hosting projects and announcements (/_announcements, /_projects), will not be migrated automatically and must be copied and modified manually.

Adjusting Front Matter#

Many of the customizations I implemented in Jekyll either do not work correctly in Hugo or cause the build process to fail. Consequently, the front matter of every Markdown file must be adjusted and, in some cases, cleaned up.

---
# Alt: So kann die Front matter einer Übersichtsseite in Jekyll aussehen
lang: de
title: Beitragsarchiv
subtitle: Diese Sammlung enthält alle meine Beiträge
layout: collection
collection: posts
permalink: /posts-archive/
entries_layout: grid
classes: wide
author_profile: false
---

In my case, there are several theme-specific parameters in the front matter, such as layout, classes, and author_profile. The lang parameter from my Jekyll internationalization extension isn’t even valid Hugo syntax; Hugo expects the language setting either as a field under params: lang or defined at the folder level. Other custom parameters tailored to personal preference can also be defined and passed via params.

Permalinks are no longer included in the front matter; instead, configuration is handled centrally↗.

Hugo-compatible front matter↗ might look like this:

---
title: Post Archive
description: This collection contains all my posts
layout: collection
---

Theme Configuration#

I can install a basic configuration for my theme using the following command:

➜  blog git:(main) ✗ git submodule add https://github.com/panr/hugo-theme-terminal ./themes/terminal

To activate it, I need to specify it in the main configuration file:

# /hugo.toml

# Add it only if you keep the theme in the `themes` directory.
# Remove it if you use the theme as a remote Hugo Module.
theme = "terminal"

And just like that, Hugo builds the site using the Terminal theme and its default colors.

However, the layout isn’t vertically centered and is too narrow for my taste; the text is quite small, and I want “my” blog colors to be different as well. Therefore, I am creating a .css file that overrides some properties of the base theme. It must be located in the /static folder and named after the theme.

/* /static/terminal.css */

:root{
  --background: #252a34;
  --background-highlight: #475064;
  --foreground: #d2eaef;
  --foreground-dimmed: #8b9ea2;
  --accent: #25a679;
  --accent-highlight: #79ae9c;
  --radius: 8px;
  --font-size: 1.35rem;
  --line-height: 1.8em;
}

/* Use system fonts, reduce transferred kB */
body{
  font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif !important; 
}

/* make content wider */
body .container{
  max-width: 70rem;
  width: 90%;
}

And just like that, it looks almost like it used to.

Organizing the folder structure#

Unlike the version of Jekyll I was using, Hugo features built-in internationalization (i18n). This requires me to restructure my folders and explicitly sort content into /de and /en directories. Instead of sitting at a higher folder level, content is now stored directly within the content folder—under /_pages, /_announcements, and /_posts—which makes things much tidier.

Before#

.
├── _announcements
├── assets
│   ├── css
│   │   ├── fontawesome
│   │   ├── katex
│   │   ├── main.scss # <-- theme import, customization
│   │   └── webfonts
│   ├── js
│   │   ├── lunr
│   │   ├── _main.js
│   │   ├── main.min.js
│   │   ├── plugins
│   │   └── vendor
│   └── video
├── banner.js
├── CNAME
├── _config.yml
├── _data
│   ├── de
│   │   ├── l10n.yml
│   └── en
│       ├── l10n.yml
├── en
│   └── index.html
├── Gemfile
├── Gemfile.lock
├── _includes # <-- Layouts (HTML), partials, 3rd-party
├── index.html # <-- Landing page
├── _layouts # <-- Page layouts
├── _pages
│   ├── 404.md # <-- German version
│   ├── [...]
│   ├── en
│   │   ├── 404.md # <-- English version
│   │   ├── [...]
├── _posts/
│   └── en   
├── _projects/
├── _sass
│   ├── minimal-mistakes # <-- Styles (SCSS) for layouts and partials
│   ├── minimal-mistakes.scss
│   └── _video.scss
├── _site/ # <-- Build artifacts
├── staticman.yml

After#

Hugo’s documentation↗ provides a good overview of the folder structure. The root folders content, layouts, and static are the most important for day-to-day work with articles and the website’s appearance.

.
├── archetypes
├── assets
├── content
│   ├── de
│   │   ├── about.md
│   │   ├── announcements/
│   │   ├── posts/
│   │   └── projects/
│   └── en
│       ├── about.md
│       ├── [...]
├── data
├── hugo.yml
├── layouts
│   ├── _default
│   │   ├── baseof.html # <-- defines header, add-ons, content, footer structure
│   │   ├── index.html # <-- landing page
│   │   ├── list.html  # <-- grid view
│   │   └── single.html # <-- post view
│   ├── _markup
│   │   └── render-link.html # <-- link highlighting and function (referrer, tabs)
│   ├── _partials
│   │   ├── cover.html # <-- cover (thumbnail) image rendering
│   │   └── math.html # <-- math rendering (katex)
│   └── _shortcodes
│       ├── audio.html
│       ├── image.html
│       └── [...]
├── resources
│   └── _gen
│       └── assets/
├── static
│   ├── assets
│   │   ├── audio/
│   │   ├── css/ # <-- contains overrides for custom layouts 
│   │   ├── docs/
│   │   ├── images/
│   │   ├── js/ # <-- math (katex) JS lives here
│   │   └── video/
│   └── terminal.css # <-- Central theme override (colors, formatting, styling)
└── themes
    └── terminal # <-- GIT submodule: Vanilla "Terminal" theme

With both solutions, layouts are defined in HTML and styles/formatting in CSS. However, since I had to use more plugins with Jekyll, the setup is more extensive.

Manual Adjustments: Shortcodes#

Hugo’s shortcodes allow you to define non-text content (media, links, formatting, styles) that is then rendered according to specific rules. To do this, you create an HTML file that defines the wrapper and includes the relevant CSS classes. You also add the desired formatting to the theme’s overriding CSS file.

Since I am by no means an expert, I simply experiment until I am happy with the layout and no longer see any artifacts or overlapping elements.

.
├── layouts
│   └── _shortcodes
│       └── my-shortcode.html # <-- Custom shortcode file
├── static
│   └── terminal.css # <-- Central theme override (colors, formatting, styling)

Syntax: Hugo and Jekyll#

In Hugo, shortcodes are represented in the Markdown file using the following syntax:

{{< shortcode-html-filename options >}}
{{< image src="/path/to/image.avif" alt="Image: alt text" position="right" >}}

By comparison, shortcode-like decorators in Jekyll using Liquid, the templating language employed by Jekyll↗ look like this:

### Liquid in interpreter code
{% Liquid bracket syntax %}
### Liquid "shortcode" pendant
{% include gallery id="gallery" caption="Eindrücke von **MobFobAmp**. Zum Vergrößern anklicken." %}
### Liquid decorator for layouting
{:.list-inline}

image#

Example of image display. A centered image follows on the next line.

The standard Markdown image syntax [Alt Text](/path/to/image) renders as a centered image without text wrapping by default in Hugo. However, for a pleasing layout, I need a few variations that require some additional CSS and HTML code.

• Centered image, no text wrapping
• Left-aligned image, text wrapping on the right
• Right-aligned image, text wrapping on the left

First, Hugo retrieves the file path and alt text. Then, it reads the desired formatting defined via the position variable from the Markdown file. Finally, it applies the image-wrapper class from the CSS file. To ensure better readability, the image alignment applies only to the desktop version of the site (>684px).

The theme customizations required to display images correctly are quite extensive. I also developed a gallery feature for posts containing a large number of images. Consequently, I wrote a separate article covering image formatting and alignment.

audio#

I use standard browser-native features to display the audio player.