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, so we created a Python-based Jekyll to Hugo converter.

Select a Hugo theme and clone the theme into your 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 config.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 config.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.

In config.yaml:

rssLimit: 10

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

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

- /old-url