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 with one of the above 13 file extensions[5] 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 meaning of a file extension by, for example, using one of the following in the YAML front matter of a content file.

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

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.
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 feedback

In the form below you can use GitHub-flavored Markdown, including emoji shortcodes from this Emoji Cheat Sheet. For example, if you want to suggest a useful link, you may want to write the string :link: which will be rendered as 🔗️.

All relevant comments are welcome, including links to your site❣︎