Hugo Gotchas
Some points which can catch you unaware when setting up the static web site generator hugo.

Reading time: 3 min.

By default no HTML in Markdown

The default setting for the standard goldmark markdown renderer is to ignore html in markdown files. Against expectations. See the closed issue Make unsafe: true the default setting for goldmark(?) #6581. The solution is to enable html inclusion in the config via

markup:
  goldmark:
    renderer:
      unsafe: false

as derived from the defaults.

Shortcodes are always on

Hugo has shortcodes for quick inline output generation. There seems to be no option to turn them off. There is a closed issue Allow disabling shortcodes #2398 about this.

The only partial migitation that I could think off would we to create own versions off all builtin shortcodes passing their content through (including the bracketing shortcode delimiters. This would likely still break the formatting of code blocks, though.

Date in archetypes

There is a well known issue date format in archetypes not possible #4053 that dateFormat in archetypes needs the special date 2006-01-02 for YYYY-MM-DD, and a permutation thereof for other combinations. The source is the discourse log.

Overlapping names

I know of no remedy yet.

Relying on index.html forwarding

Hugo renders a.md into a/index.html doc. It links to it via a/, relying on the often implemented behaviour of webservers to reply to a/ with a/index.html wikipedia. This breaks down if you want to browse the site locally without such a webserver such as in Firefox with the file:// protocol.

Ignoring paths

Ignoring files in hugo doc is not working as advertised. See issue 1559, 4874 and the pull request 5649. Paths are even more difficult.

RSS generation notice

Hugo adds the line <generator>Hugo -- gohugo.io</generator> after the <description> tag in the index.html.

Overwrite embedded rss doc src

RSS summary

If you have no summary entry in the metadata, then the rss entry contains an automatic excerpt. This could be anything.

RSS timestamp leakage

The default rss template shows very precise timestamps, which might be more precise than wanted.

Gitinfo timestamp leakage

If git integration is enabled in the config doc, then timestamps can leak via lastmod into unintended parts. See the date order configuration.

Whitespace in generated html

There is a lot of whitespace in the generated html, coming from the templates. The commandline option --minifyshould help.

Crash on css save

The local webserver started with hugo serve does not render the page if you change and save a .css file. Save a content file and it displays the site again.