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.

Conversion

Download Hugo binary

The Hugo Jekyll importer seemed broken, so we created a Python-based Jekyll to Hugo converter.

Select theme

Clone a theme into your site. Here 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 config.yaml a line:

theme: hugo-flex

Markdown syntax

Hugo Markdown parsing may use different default options or parser than Jekyll. As a result, you may need to manually fix pages' Markdown syntax.

Categories, Tags

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' {} +

and

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

Options

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

last modified metadata

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 config.yaml:

enableGitInfo: true

configure RSS

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.

In config.yaml:

rssLimit: 10

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

outputs:
  taxonomyTerm:
  - HTML
  taxonomy:
  - HTML
  section:
  - HTML

overriding theme files

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

Hugo front matter tag aliases is equivalent to Jekyll redirect_from.

aliases:
- /old-url