Hugo’s Markup Languages:
AsciiDoc, Goldmark Markdown, HTML, Org-mode, Pandoc Markdown, and reStructuredText
Updated  by  nm  2023-March-8

Page contents

News

Ongoing  According to the Repology Hugo badges, the latest packaged Hugo is version [no network :(]. To keep up with Hugo releases, see github.com/gohugoio/hugo/releases, discourse.gohugo.io/c/announcements, or @gohugoio@fosstodon.org. To learn about upcoming Hugo releases, see github.com/gohugoio/hugo/milestones.

2023-July-5  As of today, this evolving⁠[1] article has been on the web for 4 years.🕯🕯🕯🕯

2022-May-31  Hugo v0.100.0 released and, as of this version, the Blackfriday built-⁠in Markdown renderer is removed.

2022-January-12  Hugo v0.92.0 released and, as of this version, the Mmark built-⁠in Markdown renderer is removed.

2021-October-22  Joe Mooring (@jmooring) posted GitHub Issue #9074: Mismatch between content format providers and file extensions. This issue is related to the file extensions discussed in this article.

 

Markup languages known to Hugo

Hugo includes support for the following markup languages.

File
Extensions
(non-extension
identifier)		Markup LanguageBuilt-in
Renderer

.markdown
.md
.mdown[2]
(goldmark)

Goldmark-flavored Markdown

✔︎

(blackfriday)

Blackfriday-flavored Markdown
(removed in v0.100.0)

✔︎

.mmark

Mmark-flavored Markdown
(removed in v0.92.0⁠[3])

✔︎

.org

Org-mode markup[4]

✔︎

.htm
.html

HTML

✔︎

.ad
.adoc
.asciidoc[5]
(asciidocext)[6]

AsciiDoc

✘︎

.pandoc
.pdc

Pandoc
(Pandoc-flavored Markdown
and more)

✘︎

.rst

reStructuredText

✘︎

To use one of the last three markup languages, you need to install an external helper, for example asciidoctor, pandoc, or rst2html.

Hugo determines the markup language of a content file that has one of the above file extensions⁠[7] from…

  1. a markup key-value pair in the file’s front matter or

  2. the file’s file extension

The first of these found wins. This means you can override the default meaning of a file extension by putting the following in the YAML front matter of a content file.

markup: identifier

Or the following in the TOML front matter of a content file.

markup = "identifier"

Possible markup identifiers⁠[8] are in the first column of the table above. In other words, you can put one of the following in the YAML front matter of a content file.

markup: ad
markup: adoc
markup: asciidoc     # v0.73.0- (bug)
markup: asciidocext  # v0.74.0+
markup: blackfriday  # v0.60.0 – v0.99.1
markup: goldmark     # v0.60.0+
markup: markdown
markup: md
markup: mdown
markup: mmark        # v0.91.2-
markup: htm
markup: html
markup: org          # v0.19+
markup: pandoc
markup: pdc
markup: rst

 

Tips

 

 

  • If you want Hugo to process a content file, it must have front matter. If you do not need to specify metadata, use empty front matter, for example this empty YAML front matter:

    ---
---

Begin writing markup here.

    Or this empty TOML front matter:

    +++
+++

Begin writing markup here.

 

  • In Hugo v0.60.0⁠[9] and newer, the default Markdown renderer is Goldmark. You can override this for your entire site by putting the following nested map[10] in your site’s config.yaml.

    markup:
  defaultMarkdownHandler: identifier

    Or the following in your config.toml.

    [markup]
  defaultMarkdownHandler = "identifier"

    identifier can be pandoc or another Markdown handler that your version of Hugo supports.

 

ℹ

  • The defaultMarkdownHandler is used to render a content file with a .markdown, .md, or .mdown file extension (unless the front matter overrides this with a markup key-⁠value pair).

  • To learn more about configuring Markdown, and markup in general, see gohugo.io/getting-started/configuration-markup/.

 

  • In Hugo v0.59.1 and older…

    • the default Markdown renderer is Blackfriday,

    • a markup key-value pair is recognized in the front matter of a content file, but the identifiers blackfriday, goldmark, and asciidocext[6] are not available as values of this key,

    • and a markup nested map is not recognized in a config file (this site variable was introduced in v0.60.0).

 

References

To learn more about Hugo’s support for markup languages, see the following.

 

Another Org-mode option: ox-hugo

“ox-hugo is an Org exporter backend that exports Org to Hugo-compatible Markdown and also generates the front-matter (in TOML or YAML format).”

— ox-hugo.scripter.co

Another option: R Markdown & more Pandoc features via blogdown

If you install…

  1. R,

  2. R Studio IDE,

  3. and the blogdown R package, which is a wrapper around hugo,

you can create R Markdown (.Rmd) files that blogdown — along with hugo — will render to HTML. The blogdown package installs and uses rmarkdown, bookdown, and pandoc to render .Rmd files.

For more about this, see:

 

See also

For more about Hugo, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink pages, including this one, are evergreen 🌲 and regularly updated.
2. 💡You can hide a Markdown file from Hugo by using an extension that means Markdown to you and your text editor, but does not mean Markdown to Hugo, for example .markd, .mdn, or .mkd. This way you and your text editor will interpret it as a Markdown file, but Hugo won’t. I do this with backup and other Markdown files that I do not want Hugo to process. For a discussion about this, see Avoid rendering of specific .md files from blogdown::serve_site() at stackoverflow.com.
3. From Hugo v0.60.0 to v0.91.2, the Mmark built-in renderer was deprecated. It was removed in Hugo v0.92.0.
4. Starting with Hugo v0.56.0, the Org-mode markup built-in renderer is go-org. Hugo versions v0.19–v0.55.6 use goorgeous. Discussion about this in this issue.
5. The extension .asciidoc used to work but at some point (maybe v0.74.0) it quit working, which is probably a bug.
6. The markup identifier asciidocext is available in Hugo v0.74.0 and newer.
7. In the content/ directory, a file with one of the following file extensions will be interpreted by hugo as containing a known markup language: .ad, .adoc, .htm, .html, .markdown, .md, .mdown, .org, .pandoc, .pdc, or .rst.
8. Markup identifiers can also be used as an argument of Hugo’s .RenderString method.
9. As of Hugo v0.60.0, which was released on 2019-November-27, Goldmark is the default Markdown parser, the Mmark Markdown parser is deprecated, and it was announced that the Blackfriday Markdown parser will eventually be deprecated.
10. 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 ¯\_(ツ)_/¯).

Please share & discuss 📝 👎 👍 📯