Hugo Tips and Fragments
Updated  2023-March-24

Page contents

News

Ongoing  According to Repology, the latest packaged Hugo is version newest packaged version of Hugo. To keep up with Hugo releases, see github.com/gohugoio/hugo/releases, discourse.gohugo.io/c/announcements, or @GoHugoIO@twitter.com.

2023-February-1  As of today, this evolving⁠[1] article has been on the web for 3 years.🎂🎂🎂

2021-December-24  Moved the shortcode-related sections that were in this article to a new Infinite Ink article titled Hugo Shortcodes. And changed the title of this article from Hugo Tips, Shortcodes, and Fragments to Hugo Tips and Fragments.

 

Prerequisites

This article assumes you know the basics about the Hugo static site generator.

 

Shortcodes

The shortcode-related sections that used to be in this article are now in an Infinite Ink article titled Hugo Shortcodes.

 

Hugo configuration

To learn about configuring Hugo, see gohugo.io/getting-started/configuration/.

1. frontmatter

I use the following YAML nested map, which is also known as a table,⁠[2] in my config.yaml because…

  1. I want date and publishDate to mean the same thing and

  2. if no date is specified, I want a reasonably sane date (:fileModTime) to be used rather than Hugo’s default date, which is 0001-Jaunary-01.

frontmatter:
  date: 
    - publishDate
    - :filename
    - date
    - :fileModTime
  publishDate: 
    - publishDate
    - :filename
    - date
    - :fileModTime
  lastmod: 
    - lastmod
    - :fileModTime

 

For more about this, see…

The TOML syntax for this table is in fragment 3 below.

 

💡

If your Hugo content files…

  • are in a Git repository

  • and enableGitInfo is true,

you might want to include the :git date handler in some or all of your frontmatter configuration.

 

2. markup

To override Hugo’s default markup settings, use a markup nested map in your project’s config file. Here is an excerpt of Infinite Ink’s config.yaml:

markup:
  goldmark:
    parser:
      attribute:
        block: true  # default is false
    renderer:
      unsafe: true  # default is false
  highlight:
    style: manni  # default is monokai

 

Note that…

  • Without the unsafe: true setting, which is the emphasized line in this YAML fragment, raw HTML in a Goldmark-flavored Markdown source file will be replaced with <!-- raw HTML omitted --> in the markdownified⁠[3] destination file.

  • A nested-map markup setting like this does not work in the front matter of a content file. These variables must be set globally.

  • The colors and italics in this YAML excerpt are thanks to manni-⁠style syntax highlighting.

 

💡

To view examples of all possible values of markup.highlight.style, including manni and monokai, see the Chroma Style Gallery at xyproto.github.io/splash/docs/all.html.

 

For more about this, see the following.

 

3. Dividing lines in a config.toml file

When I use a config.toml, I like to include comments like the three emphasized lines below.

### ---> Put tables below non-tables <--- ###

enableEmoji = true 


### ---> Put TOML tables below here <--- ###


# next from fragment 1 above
[frontmatter]
  date = ["publishDate", ":filename", "date", ":fileModTime"]
  publishDate = ["publishDate", ":filename", "date", ":fileModTime"]
  lastmod = ["lastmod", ":fileModTime"]


# next from fragment 2 above
[markup]

  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

  [markup.highlight]
    style = "manni"


### ---> Put tables below non-tables <--- ###

 

I use these triple-⁠hash comments because I have spent a lot of time debugging Hugo websites when I, for example, put a non-table at the bottom of a config.toml.⁠😩

To learn about TOML, which is an alternative to YAML, see:

 

Commenting in website source files

Commenting is useful for writing notes to yourself and for holding fragments that you have used in the past or may use in the future. To learn about the comment syntax of many languages, see Infinite Ink’s Commenting Code Cheatsheet.

 

4. Commenting out executable code

In Go Template code, which is also known as Go HTML,⁠[4] you can comment out⁠[5] executable code with the following single- or multi-⁠line comment syntax.

{{/* Go HTML single-line comment */}}


{{/*

Go HTML
multi-line
comment

*/}}

The following also work.

{{- /* Go HTML single-line comment */ -}}


{{- /*

Go HTML
multi-line
comment

*/ -}}

Note that in this second style of Go Template comment syntax, a single space is required between each dash (-)[6] and its corresponding forward slash (/).

 

5. Commenting out notes and non-executable code

In a layout file or a Markdown content file, you can comment out text (such as an English-language note to yourself) or non-executable code with the following single- or multi-line comment syntax.

<!--  HTML or Markdown single-line comment -->

<!--

HTML or Markdown
multi-line
comment

-->
‼
Do not use these HTML-style comments to comment out executable Go Template code in a Hugo layout file. If you do, Hugo will process the executable code and potentially generate error messages or change the layout logic.

 

6. Oddity about commenting in a block layout file

In a child block layout file, do not put a comment — or anything other than blank lines — outside a define-end container:

only blank lines here

{{ define "main" }}

Go Template code and comments here

{{ end }}

only blank lines here

 

Escaping strings in content files from Hugo processing

7. Escaping emoji codes

In Infinite Ink’s Hugo Tutorial, in step 13.2.2. Include emoji codes I wrote about the following emoji codes.

:man_astronaut:
:star:
:woman_astronaut:
:bulb:
:wrench:
:sparkles:

Since I have enableEmoji: true in my config.yaml, Hugo emojifies the above strings in a content file to:

👨‍🚀
⭐
👩‍🚀
💡
🔧
✨

So how do you write about these strings without Hugo emojifying them? There is more than one way to escape emoji codes. The way I do it is to use an HTML entity for one of the colons in each emoji code. For example:

:man_astronaut&#58;
:star&#58;
:woman_astronaut&#58;
:bulb&#58;
:wrench&#58;
:sparkles&#58;
ℹ

This trick works…

  • in some parts of a Markdown content file, but does not work in Markdown inline code or in a Markdown code block

  • throughout an AsciiDoc content file, but sometimes needs [subs="replacements"]

 

8. Escaping and commenting out Hugo shortcodes

In a Hugo content file, shortcodes are called using either the delimiters {{< and >}} or the delimiters {{% and %}}.

 

8.1. Escaping shortcodes

If you want to write about shortcodes, as I do in Infinite Ink’s Hugo Shortcodes, you need to escape these strings from being interpreted as being part of actual shortcode calls. Hugo uses the following syntax to escape these delimiters in a content source file:

{{</* something */>}}
   ^^           ^^
   Note         Note

{{%/* something */%}}
   ^^           ^^
   Note         Note

If you use the above delimiters in a content file, they will be rendered in the destination file as:

{{< something >}}

{{% something %}}

And these strings will not be interpreted as shortcode calls.

 

ℹ
I learned about escaping Hugo shortcodes in the discourse.gohugo.io thread How is the Hugo Doc site showing shortcodes in code blocks?

 

️8.2. Commenting out shortcodes in Markdown

To comment out a shortcode in a Markdown (.markdown, .md, or .mdown) content source file, you can do this:

<!--
{ {< shortcode call >}}
-->

Notice the space between the two leading curly braces. Actually any character between the curly braces will denature the shortcode. For example, I like to use an exclamation mark because it is more noticeable than a space character:

<!--
{!{< shortcode call >}}
-->

 

️8.3. Commenting out shortcodes in AsciiDoc

To comment out a shortcode in an AsciiDoc (.ad, .adoc, or .asciidoc) content source file, you can do this:

////
{!{< shortcode call >}}
////

Or this:

// {!{< shortcode call >}}

 

💡
If you really want it to be noticeable that a shortcode is commented out, you could use !!! rather than ! to denature a shortcode call.

 

 

See also

For more about Hugo, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. A nested map is also known as an associative array, a dictionary, a dict, a hash table, a hash, a keyed list, a map, a mapping, a named map, an object, a record, a struct, or a table. For more about this data-serialization object, see Infinite Ink’s YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)_/¯).
3. In Hugo, markdownify means convert Markdown to HTML.
4. Go Template code is also known as Go HTML. For details, see gohugo.io/categories/templates/, golang.org/pkg/html/template/, and golang.org/pkg/text/template/.
5. The phrase “comment out” is discussed in english.stackexchange.com/questions/33483/when-i-say-comment-out-does-it-mean-to-uncomment-something-or-comment-it.
6. The Unicode name for the “dash” character (-) is “hyphen-minus,” but its proper name is rarely used. Instead, it is usually called “dash,” “hyphen,” or “minus.” Details are at wikipedia.org’s Hyphen-minus.

Discuss or share 📝 🤔 🐘