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



Page contents


Markup languages known to Hugo

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

Markup LanguageBuilt-in


Goldmark-flavored Markdown



Blackfriday-flavored Markdown
(will be deprecated)



Mmark-flavored Markdown











(Pandoc-flavored Markdown
and more)



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[6] 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     # v0.60.0+
markup: blackfriday  # v0.60.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[7] in your site’s config.yaml.

  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 and goldmark are not available as values of this key,

  • and a markup nested map is not recognized in a config file (this global 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:


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
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 file extensions of AsciiDoc files. This is useful if you want to hide the AsciiDocness of a content file, for example an include file, from Hugo.
6. 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.
7. 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 reaction or comment to this page, you need a GitHub account and your browser needs to be able to run a script that is hosted at