Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, & reStructuredText
Updated 2021-May-14

Page contents


2020-July-13  Hugo v0.74.0 released with “reworked external Asciidoctor integration.” To learn about this, see the v0.74.0 release notes,, and Thank you @muenchhausen (Derk Muenchhausen), @bwklein (Bryan Klein), @helfper (Helder Pereira), and all Hugo contributors!

2020-July-5  As of today, this evolving⁠[1] article has been on the web for one year.🎂

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

Hugo determines the markup language of a content file that has one of the above 13 file extensions⁠[7] 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

Or the following in the TOML front matter of a content file.

markup = "identifier"

The 16 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+




  • If you want Hugo to process a content file, it must have front matter. If you do not need to specify metadata, use empty front matter, for example this empty YAML front matter:

    Begin writing markup here.

    Or this empty TOML front matter:

    Begin writing markup here.


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

      defaultMarkdownHandler: identifier

    Or the following in your config.toml.

      defaultMarkdownHandler = "identifier"

    identifier can by blackfriday, mmark, etc.


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


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


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
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 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 13 file extensions will be interpreted by hugo as containing a known markup language: .ad, .adoc, .asciidoc, .htm, .html, .markdown, .md, .mdown, .mmark, .pandoc, .pdc, .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.

Comments & reactions 👍 👎 📝

To comment or react, you must be signed in to GitHub.