Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, & reStructuredText
Updated 2021-September-11

Page contents

News

2021-August-3  As of Hugo v0.87.0, which was released 2021-August-3, the Blackfriday built-in renderer is deprecated.

2021-July-5  As of today, this evolving⁠[1] article has been on the web for 2 years.🎂🎂

2019-November-27  As of Hugo v0.60.0, which was released 2019-November-27, the Mmark built-in renderer is deprecated. There is a GitHub issue about upgrading Mmark rather than dropping it. In September 2021, this issue has 11 up votes.⁠👍⁠👍👍👍👍👍👍👍👍👍⁠👍

 

Markup languages known to Hugo

Hugo versions 0.60.0⁠[2] and newer include support for the following markup languages.

Default
File
Extensions
(non-extension
identifier)
Markup Language Built-in
Renderer

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

Goldmark-flavored Markdown

✔︎

(blackfriday)

Blackfriday-flavored Markdown
(deprecated⁠[4])

✔︎

.mmark

Mmark-flavored Markdown
(deprecated⁠[5])

✔︎

.org

Org-mode[6]

✔︎

.htm
.html

HTML

✔︎

.ad
.adoc
.asciidoc[7]
(asciidocext)[8]

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 13 file extensions⁠[9] 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 that 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⁠[10] are in the first column of the table above. In Hugo v0.74.0 through v0.88.1, you can put one of the following in the YAML front matter of a content file.

markup: ad
markup: adoc
markup: asciidoc
markup: asciidocext  # v0.74.0+
markup: blackfriday  # v0.60.0+
markup: goldmark     # v0.60.0+
markup: markdown
markup: md
markup: mdown
markup: mmark        # v0.88.1-
markup: htm
markup: html
markup: org
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[2] and newer, the default Markdown renderer is Goldmark. You can override this for your entire site by putting the following nested map[11] in your site’s config.yaml.

    markup:
      defaultMarkdownHandler: identifier

    Or the following in your config.toml.

    [markup]
      defaultMarkdownHandler = "identifier"

    identifier can by blackfriday, mmark, etc.

 

  • 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[8] 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).”

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

Endnotes


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. 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.
3. 💡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.
4. As of Hugo v0.87.0, the Blackfriday built-in renderer is deprecated.
5. As of Hugo v0.60.0, the Mmark built-in renderer is deprecated.
6. Starting with Hugo v0.56.0, the Org-mode built-in renderer is go-org. Hugo versions 0.55.6 and older use goorgeous. Discussion about this in this issue.
7. In addition to .asciidoc, .adoc, and .ad, Asciidoctor also recognizes .asc and .txt as a file extension of an AsciiDoc file. This is useful if you want to hide the AsciiDocness of a content file, for example an include file, from Hugo.
8. The markup identifier asciidocext is available in Hugo v0.74.0 and newer.
9. In the content/ directory, a file with one of the following 13 file extensions will be interpreted by hugo as containing a known markup language: .ad, .adoc, .asciidoc, .htm, .html, .markdown, .md, .mdown, .mmark, .pandoc, .pdc, .org, or .rst.
10. Markup identifiers can also be used as an argument of Hugo’s RenderString function.
11. A nested map is also known as an associative array, a dictionary, a dict, a hash table, a hash, a map, a mapping, a named map, an object, or a table. For more about this data-serialization object, see Infinite Ink’s YAML Includes Atoms, Maps, and Lists (Featuring the String ¯∖_(ツ)_/¯).

Comments 👍 👎 📝

Please comment so I know I'm not speaking into the void. Also, your public comment might improve this page or help me to improve this page.