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

HIDDEN[1]

 

Page contents

Markup languages known to Hugo

Hugo includes support for the following markup languages.

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

.markdown
.md
.mdown
(goldmark)

Goldmark-flavored Markdown

✔︎

(blackfriday)

Blackfriday-flavored Markdown[2]

✔︎

.mmark

Mmark-flavored Markdown[2]

✔︎

.org

Org-mode[3]

✔︎

.htm
.html

HTML

✔︎

.ad
.adoc
.asciidoc[4]

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 asciidoc, asciidoctor, pandoc, or rst2html.

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

  1. a markup parameter in the file’s front matter

  2. or 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 identifiers 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     # available in v0.60.0+
markup: blackfriday  # available in v0.60.0+

 

‼︎

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

markup:
  defaultMarkdownHandler: blackfriday

In v0.59.1 and earlier

  • the default Markdown renderer is Blackfriday

  • and the identifiers blackfriday and goldmark are not available as possible values for the front-matter markup parameter.

 

To learn more about Hugo’s support for markup languages, see gohugo.io’s…

 

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

Infinite Ink’s #gohugo is a portal to the Hugo world.

Notes

Discussion and reactions


1. An earlier version of this article was in Infinite Ink’s TGIH: Themeless & Gitless Introduction to Hugo in the section called “7.1 About Hugo’s markup languages.”
2. Two of Hugo’s Markdown renderers, Blackfriday and Mmark, will eventually be removed from Hugo.
3. Starting with Hugo v0.56.0, the Org-mode built-in renderer is go-org. Hugo v0.55.6 and earlier use goorgeous. Discussion about this in this issue.
5. 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

Discussion and reactions

Please post a comment or reaction so I know that someone other than me has read this. Thanks to Utterances and GitHub, the possible reactions are 👍️ 👎️ 😂️ 🎉️ 😕️ ❤️ 🚀️ and 👀️.