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

HIDDEN[1]

 

Markup languages known to Hugo

Hugo includes support for the following markup languages.

File
Extension(s)
Markup LanguageBuilt-in
Helper
(Renderer)

.md
.mdown
.markdown

Blackfriday-flavored Markdown[2]

✔︎

.mmark

Mmark-flavored Markdown[2]

✔︎

.org

Org-mode[3]

✔︎

.htm
.html

HTML

✔︎

.ad
.adoc
.asciidoc[4]

AsciiDoc

.pdc
.pandoc

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

Hugo determines the markup language of a file in the content/ directory from:

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

  2. the file’s file extension

The first of these found wins.

If you want to use a markup key in the front matter, the possible values are bolded in the File Extension(s) column in the table above. In other words, any one of the following would work in YAML front matter (assuming that the corresponding helper app is either built in to Hugo, or is installed on your platform and is on your path).

markup: markdown
markup: mmark
markup: org
markup: html
markup: asciidoc
markup: pandoc
markup: rst

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

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.


1. An earlier version of this article was in Infinite Ink’s TGIH: Themeless & Gitless Introduction to Hugo in a section called “7.1 About Hugo’s markup languages.”
2. Two of Hugo’s Markdown renderers, Blackfriday and Mmark, need to be updated. For information about this, see the GitHub issues The Markdown Pickle and Investigate use of Goldmark.
3. Starting with Hugo v0.56.0, the Org-mode built-in helper is go-org. Hugo v0.55.6 and earlier use goorgeous. Discussion about this in this issue.