Configure markup
Default handler
Hugo uses Goldmark to render Markdown to HTML.
[markup] defaultMarkdownHandler = 'goldmark'
Files with the .md or .markdown extension are processed as Markdown, provided that you have not specified a different content format using the markup field in front matter.
To use a different renderer for Markdown files, specify one of asciidocext, org, pandoc, or rst in your site configuration.
| defaultMarkdownHandler | Description |
|---|---|
asciidocext | AsciiDoc |
goldmark | Goldmark |
org | Emacs Org Mode |
pandoc | Pandoc |
rst | reStructuredText |
To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your security policy.
Unless you need a unique capability provided by one of the alternate Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the CommonMark specification, and is compatible with GitHub Flavored Markdown (GFM).
Goldmark
This is the default configuration for the Goldmark Markdown renderer:
Goldmark extensions
The extensions below, excluding Extras and Passthrough, are enabled by default.
| Extension | Documentation | Enabled |
|---|---|---|
| cjk | Goldmark Extensions: CJK | ✔️ |
| definitionList | PHP Markdown Extra: Definition lists | ✔️ |
| extras | Hugo Goldmark Extensions: Extras | |
| footnote | PHP Markdown Extra: Footnotes | ✔️ |
| linkify | GitHub Flavored Markdown: Autolinks | ✔️ |
| passthrough | Hugo Goldmark Extensions: Passthrough | |
| strikethrough | GitHub Flavored Markdown: Strikethrough | ✔️ |
| table | GitHub Flavored Markdown: Tables | ✔️ |
| taskList | GitHub Flavored Markdown: Task list items | ✔️ |
| typographer | Goldmark Extensions: Typographer | ✔️ |
Extras
Enable deleted text, inserted text, mark text, subscript, and superscript elements in Markdown.
| Element | Markdown | Rendered |
|---|---|---|
| Deleted text | ~~foo~~ | <del>foo</del> |
| Inserted text | ++bar++ | <ins>bar</ins> |
| Mark text | ==baz== | <mark>baz</mark> |
| Subscript | H~2~O | H<sub>2</sub>O |
| Superscript | 1^st^ | 1<sup>st</sup> |
To avoid a conflict when enabling the Hugo Goldmark Extras subscript extension, if you want to render subscript and strikethrough text concurrently you must:
- Disable the Goldmark strikethrough extension
- Enable the Hugo Goldmark Extras delete extension
For example:
[markup.goldmark.extensions] strikethrough = false
[markup.goldmark.extensions.extras.delete] enable = true
[markup.goldmark.extensions.extras.subscript] enable = true
Passthrough
Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See mathematics in Markdown for details.
Typographer
The Typographer extension replaces certain character combinations with HTML entities as specified below:
| Markdown | Replaced by | Description |
|---|---|---|
... | … | horizontal ellipsis |
' | ’ | apostrophe |
-- | – | en dash |
--- | — | em dash |
« | « | left angle quote |
“ | “ | left double quote |
‘ | ‘ | left single quote |
» | » | right angle quote |
” | ” | right double quote |
’ | ’ | right single quote |
Goldmark settings explained
Most of the Goldmark settings above are self-explanatory, but some require explanation.
duplicateResourceFiles
(bool) If true, shared page resources on multilingual single-host sites will be duplicated for each language. See multilingual page resources for details. Default is false.
With multilingual single-host sites, setting this parameter to false will enable Hugo's embedded link render hook and embedded image render hook. This is the default configuration for multilingual single-host sites.
parser.wrapStandAloneImageWithinParagraph
(bool) If true, image elements without adjacent content will be wrapped within a p element when rendered. This is the default Markdown behavior. Set to false when using an image render hook to render standalone images as figure elements. Default is true.
parser.autoHeadingIDType
(string) The strategy used to automatically generate heading id attributes, one of github, github-ascii or blackfriday.
githubproduces GitHub-compatibleidattributesgithub-asciidrops any non-ASCII characters after accent normalizationblackfridayproducesidattributes compatible with the Blackfriday Markdown renderer
This is also the strategy used by the anchorize template function. Default is github.
parser.attribute.block
(bool) If true, enables Markdown attributes for block elements. Default is false.
parser.attribute.title
(bool) If true, enables Markdown attributes for headings. Default is true.
renderHooks.image.enableDefault
(bool) If true, enables Hugo's embedded image render hook. Default is false.
The embedded image render hook is automatically enabled for multilingual single-host sites if duplication of shared page resources is disabled. This is the default configuration for multilingual single-host sites.
renderHooks.link.enableDefault
(bool) If true, enables Hugo's embedded link render hook. Default is false.
The embedded link render hook is automatically enabled for multilingual single-host sites if duplication of shared page resources is disabled. This is the default configuration for multilingual single-host sites.
renderer.hardWraps
(bool) If true, Goldmark replaces newline characters within a paragraph with br elements. Default is false.
renderer.unsafe
(bool) If true, Goldmark renders raw HTML mixed within the Markdown. This is unsafe unless the content is under your control. Default is false.
AsciiDoc
This is the default configuration for the AsciiDoc renderer:
AsciiDoc settings explained
attributes
(map) A map of key-value pairs, each a document attributes,See Asciidoctor’s attributes.
backend
(string) The backend output file format. Default is html5.
extensions
(string array) An array of enabled extensions, one or more of asciidoctor-html5s, asciidoctor-bibtex, asciidoctor-diagram, asciidoctor-interdoc-reftext, asciidoctor-katex, asciidoctor-latex, asciidoctor-mathematical, or asciidoctor-question.
To mitigate security risks, entries in the extension array may not contain forward slashes (/), backslashes (\), or periods. Due to this restriction, extensions must be in Ruby's $LOAD_PATH.
failureLevel
(string) The minimum logging level that triggers a non-zero exit code (failure). Default is fatal.
noHeaderOrFooter
(bool) If true, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is true.
preserveTOC
(bool) If true, preserves the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the TableOfContents method on a Page object in your templates. Default is false.
safeMode
(string) The safe mode level, one of unsafe, safe, server, or secure. Default is unsafe.
sectionNumbers
(bool) If true, numbers each section title. Default is false.
trace
(bool) If true, include backtrace information on errors. Default is false.
verbose
(bool)If true, verbosely prints processing information and configuration file checks to stderr. Default is false.
workingFolderCurrent
(bool) If true, sets the working directory to be the same as that of the AsciiDoc file being processed, allowing includes to work with relative paths. Set to true to render diagrams with the asciidoctor-diagram extension. Default is false.
AsciiDoc configuration example
AsciiDoc troubleshooting
Run hugo --logLevel debug to examine Hugo's call to the Asciidoctor executable:
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
Highlight
This is the default highlight configuration. Note that some of these settings can be set per code block, see Syntax Highlighting.
For style, see these galleries:
For CSS, see Generate Syntax Highlighter CSS.
Table of contents
This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
startLevel
(int) Heading levels less than this value will be excluded from the table of contents. For example, to exclude h1 elements from the table of contents, set this value to 2. Default is 2.
endLevel
(int) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude h4, h5, and h6 elements from the table of contents, set this value to 3. Default is 3.
ordered
(bool) If true, generates an ordered list instead of an unordered list. Default is false.