{{/* Go HTML single-line comment */}} {{/* Go HTML multi-line comment */}}
Ongoing
According to
Repology,
the latest
packaged Hugo
is
.
2023-February-1
As of today, this evolving[1]
article
has been on
the web
for
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.
This article assumes you know the basics about the Hugo static site generator.
The shortcode-related sections that used to be in this article are now in an Infinite Ink article titled Hugo Shortcodes.
To learn about configuring Hugo, see gohugo.io/getting-started/configuration/.
I want date
and publishDate
to mean the same thing
and
if no date is specified, I want
a
reasonably sane date (:fileModTime
) to be used
rather than
Hugo’s default date, which is
frontmatter:
date:
- publishDate
- :filename
- date
- :fileModTime
publishDate:
- publishDate
- :filename
- date
- :fileModTime
lastmod:
- lastmod
- :fileModTime
For more about this, see…
gohugo.io/getting-started/configuration/#configure-front-matter
and Stackoverflow.com’s Hugo Date vs PublishDate, which includes an answer by n m (i.e. me😄).
The TOML syntax for this table is in fragment 3 below.
💡 | If your Hugo content files…
you might
want to include the |
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
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
|
For more about this, see the following.
gohugo.io:
ii.com:
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 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.
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 (/
).
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. |
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
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: :star: :woman_astronaut: :bulb: :wrench: :sparkles:
ℹ | This trick works…
|
In a Hugo content file, shortcodes are
called using either
the delimiters
{{<
and >}}
or
the delimiters
{{%
and %}}
.
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? |
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 >}} -->
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. |
For more about Hugo, see Infinite Ink’s…
🔗 Linkified Section Headings in Hugo-Generated Web Pages (featuring Markdown and AsciiDoc examples)
Transforming Text with Hugo (featuring plainify
, htmlUnescape
, and more)
A Way to Compare Hugo’s Markup Languages (featuring inline footnotes)📊
Hugo’s Markup Languages: AsciiDoc, HTML, Markdown,
Hugo’s .RenderString
Method (featuring AsciiDoc admonitions in Markdown and Go HTML)
Variable and Parameter Names in Hugo (featuring camelCase🐫 and snake_case🐍)
Hugo Shortcodes: Including Go Templates in Hugo Content Files
Configuring Security in Hugo (featuring settings needed to use Asciidoctor and Pandoc)🔒
TGIH: Themeless & Gitless Introduction to the Hugo SSG (a tutorial)
-
) 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.@nm@mathstodon.xyz
or
#InfiniteInk
in it.