Configure markup
Default handler
Hugo uses Goldmark to render Markdown to HTML.
markup:
defaultMarkdownHandler: goldmark
[markup]
defaultMarkdownHandler = 'goldmark'
{
"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.
Goldmark
This is the default configuration for the Goldmark Markdown renderer:
markup:
goldmark:
duplicateResourceFiles: false
extensions:
cjk:
eastAsianLineBreaks: false
eastAsianLineBreaksStyle: simple
enable: false
escapedSpace: false
definitionList: true
extras:
delete:
enable: false
insert:
enable: false
mark:
enable: false
subscript:
enable: false
superscript:
enable: false
footnote: true
linkify: true
linkifyProtocol: https
passthrough:
delimiters:
block: []
inline: []
enable: false
strikethrough: true
table: true
taskList: true
typographer:
apostrophe: '’'
disable: false
ellipsis: '…'
emDash: '—'
enDash: '–'
leftAngleQuote: '«'
leftDoubleQuote: '“'
leftSingleQuote: '‘'
rightAngleQuote: '»'
rightDoubleQuote: '”'
rightSingleQuote: '’'
parser:
attribute:
block: false
title: true
autoHeadingID: true
autoHeadingIDType: github
wrapStandAloneImageWithinParagraph: true
renderHooks:
image:
enableDefault: false
link:
enableDefault: false
renderer:
hardWraps: false
unsafe: false
xhtml: false
[markup]
[markup.goldmark]
duplicateResourceFiles = false
[markup.goldmark.extensions]
definitionList = true
footnote = true
linkify = true
linkifyProtocol = 'https'
strikethrough = true
table = true
taskList = true
[markup.goldmark.extensions.cjk]
eastAsianLineBreaks = false
eastAsianLineBreaksStyle = 'simple'
enable = false
escapedSpace = false
[markup.goldmark.extensions.extras]
[markup.goldmark.extensions.extras.delete]
enable = false
[markup.goldmark.extensions.extras.insert]
enable = false
[markup.goldmark.extensions.extras.mark]
enable = false
[markup.goldmark.extensions.extras.subscript]
enable = false
[markup.goldmark.extensions.extras.superscript]
enable = false
[markup.goldmark.extensions.passthrough]
enable = false
[markup.goldmark.extensions.passthrough.delimiters]
block = []
inline = []
[markup.goldmark.extensions.typographer]
apostrophe = '’'
disable = false
ellipsis = '…'
emDash = '—'
enDash = '–'
leftAngleQuote = '«'
leftDoubleQuote = '“'
leftSingleQuote = '‘'
rightAngleQuote = '»'
rightDoubleQuote = '”'
rightSingleQuote = '’'
[markup.goldmark.parser]
autoHeadingID = true
autoHeadingIDType = 'github'
wrapStandAloneImageWithinParagraph = true
[markup.goldmark.parser.attribute]
block = false
title = true
[markup.goldmark.renderHooks]
[markup.goldmark.renderHooks.image]
enableDefault = false
[markup.goldmark.renderHooks.link]
enableDefault = false
[markup.goldmark.renderer]
hardWraps = false
unsafe = false
xhtml = false
{
"markup": {
"goldmark": {
"duplicateResourceFiles": false,
"extensions": {
"cjk": {
"eastAsianLineBreaks": false,
"eastAsianLineBreaksStyle": "simple",
"enable": false,
"escapedSpace": false
},
"definitionList": true,
"extras": {
"delete": {
"enable": false
},
"insert": {
"enable": false
},
"mark": {
"enable": false
},
"subscript": {
"enable": false
},
"superscript": {
"enable": false
}
},
"footnote": true,
"linkify": true,
"linkifyProtocol": "https",
"passthrough": {
"delimiters": {
"block": [],
"inline": []
},
"enable": false
},
"strikethrough": true,
"table": true,
"taskList": true,
"typographer": {
"apostrophe": "\u0026rsquo;",
"disable": false,
"ellipsis": "\u0026hellip;",
"emDash": "\u0026mdash;",
"enDash": "\u0026ndash;",
"leftAngleQuote": "\u0026laquo;",
"leftDoubleQuote": "\u0026ldquo;",
"leftSingleQuote": "\u0026lsquo;",
"rightAngleQuote": "\u0026raquo;",
"rightDoubleQuote": "\u0026rdquo;",
"rightSingleQuote": "\u0026rsquo;"
}
},
"parser": {
"attribute": {
"block": false,
"title": true
},
"autoHeadingID": true,
"autoHeadingIDType": "github",
"wrapStandAloneImageWithinParagraph": true
},
"renderHooks": {
"image": {
"enableDefault": false
},
"link": {
"enableDefault": false
}
},
"renderer": {
"hardWraps": false,
"unsafe": false,
"xhtml": false
}
}
}
}
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
New in v0.126.0Enable 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:
extras:
delete:
enable: true
subscript:
enable: true
strikethrough: false
[markup]
[markup.goldmark]
[markup.goldmark.extensions]
strikethrough = false
[markup.goldmark.extensions.extras]
[markup.goldmark.extensions.extras.delete]
enable = true
[markup.goldmark.extensions.extras.subscript]
enable = true
{
"markup": {
"goldmark": {
"extensions": {
"extras": {
"delete": {
"enable": true
},
"subscript": {
"enable": true
}
},
"strikethrough": false
}
}
}
}
Passthrough
New in v0.122.0Enable 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
New in v0.123.0(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
.
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
.
github
produces GitHub-compatibleid
attributesgithub-ascii
drops any non-ASCII characters after accent normalizationblackfriday
producesid
attributes 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
New in v0.123.0(bool
) If true
, enables Hugo’s embedded image render hook. Default is false
.
renderHooks.link.enableDefault
New in v0.123.0(bool
) If true
, enables Hugo’s embedded link render hook. Default is false
.
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:
markup:
asciidocExt:
attributes: {}
backend: html5
extensions: []
failureLevel: fatal
noHeaderOrFooter: true
preserveTOC: false
safeMode: unsafe
sectionNumbers: false
trace: false
verbose: false
workingFolderCurrent: false
[markup]
[markup.asciidocExt]
backend = 'html5'
extensions = []
failureLevel = 'fatal'
noHeaderOrFooter = true
preserveTOC = false
safeMode = 'unsafe'
sectionNumbers = false
trace = false
verbose = false
workingFolderCurrent = false
[markup.asciidocExt.attributes]
{
"markup": {
"asciidocExt": {
"attributes": {},
"backend": "html5",
"extensions": [],
"failureLevel": "fatal",
"noHeaderOrFooter": true,
"preserveTOC": false,
"safeMode": "unsafe",
"sectionNumbers": false,
"trace": false,
"verbose": false,
"workingFolderCurrent": false
}
}
}
AsciiDoc settings explained
attributes
(map
) A map of key-value pairs, each a document attribute. 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
.
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
markup:
asciidocExt:
attributes:
my-attribute-name: my value
my-base-url: https://example.com/
extensions:
- asciidoctor-html5s
- asciidoctor-diagram
workingFolderCurrent: true
[markup]
[markup.asciidocExt]
extensions = ['asciidoctor-html5s', 'asciidoctor-diagram']
workingFolderCurrent = true
[markup.asciidocExt.attributes]
my-attribute-name = 'my value'
my-base-url = 'https://example.com/'
{
"markup": {
"asciidocExt": {
"attributes": {
"my-attribute-name": "my value",
"my-base-url": "https://example.com/"
},
"extensions": [
"asciidoctor-html5s",
"asciidoctor-diagram"
],
"workingFolderCurrent": true
}
}
}
AsciiDoc syntax highlighting
Follow the steps below to enable syntax highlighting.
- Step 1
- Set the
source-highlighter
attribute in your site configuration. For example:
markup:
asciidocExt:
attributes:
source-highlighter: rouge
[markup]
[markup.asciidocExt]
[markup.asciidocExt.attributes]
source-highlighter = 'rouge'
{
"markup": {
"asciidocExt": {
"attributes": {
"source-highlighter": "rouge"
}
}
}
}
- Step 2
- Generate the highlighter CSS. For example:
rougify style monokai.sublime > assets/css/syntax.css
- Step 3
- In your base template add a link to the CSS file:
<head>
...
{{ with resources.Get "css/syntax.css" }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
...
</head>
Then add the code to be highlighted to your markup:
[#hello,ruby]
----
require 'sinatra'
get '/hi' do
"Hello World!"
end
----
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.
markup:
highlight:
anchorLineNos: false
codeFences: true
guessSyntax: false
hl_Lines: ""
hl_inline: false
lineAnchors: ""
lineNoStart: 1
lineNos: false
lineNumbersInTable: true
noClasses: true
noHl: false
style: monokai
tabWidth: 4
[markup]
[markup.highlight]
anchorLineNos = false
codeFences = true
guessSyntax = false
hl_Lines = ''
hl_inline = false
lineAnchors = ''
lineNoStart = 1
lineNos = false
lineNumbersInTable = true
noClasses = true
noHl = false
style = 'monokai'
tabWidth = 4
{
"markup": {
"highlight": {
"anchorLineNos": false,
"codeFences": true,
"guessSyntax": false,
"hl_Lines": "",
"hl_inline": false,
"lineAnchors": "",
"lineNoStart": 1,
"lineNos": false,
"lineNumbersInTable": true,
"noClasses": true,
"noHl": false,
"style": "monokai",
"tabWidth": 4
}
}
}
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:
markup:
tableOfContents:
endLevel: 3
ordered: false
startLevel: 2
[markup]
[markup.tableOfContents]
endLevel = 3
ordered = false
startLevel = 2
{
"markup": {
"tableOfContents": {
"endLevel": 3,
"ordered": false,
"startLevel": 2
}
}
}
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
.