Switching from Jekyll to Hugo

Hugo can have 100x faster build times than Jekyll. Hugo offers a more powerful design experience. We recommend Hugo in general for fast, HTML5 standard compliant and robust static site generation.

Download Hugo binary The Hugo Jekyll importer seemed broken. This Python-based Jekyll to Hugo converter can be used instead.

Select a Hugo theme and clone the theme into the site. We use “hugo-flex” theme–we have an example hugo-flex template.

cd ~/myHugoSite

git submodule add https://github.com/de-souza/hugo-flex themes/hugo-flex

Enable the theme by adding to hugo.yaml a line:

theme: hugo-flex

Hugo Markdown parsing may use different default options or parser than Jekyll. As a result, you may need to manually fix pages’ Markdown syntax. You may need to rewrite the internal page links to categories and tags, something perhaps like:

find content -type f -name "*.md" -execdir sed -i 's,](/category/#,](/categories/,g' {} +

find content -type f -name "*.md" -execdir sed -i 's,](/tag/#,](/tags/,g' {} +

To convert options you might see in examples between TOML and YaML etc. consider this web converter.

Sometimes you make minor updates to a blog post without wanting to change the main posted date of the article. To have this update time reflected in the article metadata, telling search engines the “freshness” of the article, enable the last updated metadata from Git commit time by adding to hugo.yaml:

enableGitInfo: true

It’s typically beneficial to set a limit to the number of posts in the site RSS feed. This can speed the site build by a factor a 10 for large sites, and improve the update speed of search engines. Check that the RSS limit is working by checking localhost:1313/index.xml from the site preview hugo serve -O.

In hugo.yaml:

rssLimit: 10

To disable RSS for taxonomies (tags, categories) that aren’t useful for many site, additionally add to hugo.yaml:

outputs:
  taxonomy:
  - HTML
  section:
  - HTML

A key design pattern in Hugo is overriding theme files without editing the theme files themselves that are in a Git submodule. Use the lookup order for partials and templates. This will keep your web design clean, minimal and DRY.

Redirect page URL with Hugo front matter tag aliases, equivalent to Jekyll redirect_from.

aliases:
- /old-url