Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, & reStructuredText[1]

HIDDEN[1]

 

Page contents

News

2020-July-13  Hugo v0.74.0 released with “reworked external Asciidoctor integration.” To learn about this, see the v0.74.0 release notes, github.com/gohugoio/hugo/pull/7281, and gohugo.io/content-management/formats/. Thank you @muenchhausen (Derk Muenchhausen), @bwklein (Bryan Klein), and all Hugo contributors!👏

Markup languages known to Hugo

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

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

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

Goldmark-flavored Markdown

✔︎

(blackfriday)

Blackfriday-flavored Markdown
(will be deprecated)

✔︎

.mmark

Mmark-flavored Markdown
(deprecated)

✔︎

.org

Org-mode[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 renderer, for example asciidoctor, pandoc, or rst2html.

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

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

  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

Possible markup identifiers[8] are in the first column of the table above. For example, you could use one of the following.

markup: markdown
markup: mmark
markup: org
markup: html
markup: asciidoc
markup: pandoc
markup: rst
markup: goldmark     # v0.60.0+
markup: blackfriday  # v0.60.0+
markup: asciidocext  # v0.74.0+

 

In Hugo v0.60.0[2] and later the default Markdown renderer is Goldmark. You can override this for your entire site by putting something like the following nested map[9] in your site’s config.yaml.

markup:
  defaultMarkdownHandler: blackfriday

 

In Hugo v0.59.1 and earlier

  • 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).

 

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:

Endnotes


1. An earlier version of this article was in Infinite Ink’s Hugo Tutorial: Themeless & Gitless Introduction to Hugo in step 7.1 Content markup languages.
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. Starting with Hugo v0.56.0, the Org-mode built-in renderer is go-org. Hugo versions 0.55.6 and earlier use goorgeous. Discussion about this in this issue.
5. 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.
6. The markup identifier asciidocext is available in Hugo v0.74.0 and later.
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, .asciidoc, .htm, .html, .markdown, .md, .mdown, .mmark, .pdc, .pandoc, .org, or .rst.
8. Markup identifiers can also be used as an argument of Hugo’s RenderString function.
9. 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.

Edit this page 📝

To add a comment or reaction emoji (👍 👎 😂 🎉 😕 ❤ 🚀 or 👀) to this page, you need JavaScript enabled in your browser and a GitHub account.