配置标记
默认处理程序
Hugo 使用 Goldmark 将 Markdown 渲染为 HTML。
markup:
defaultMarkdownHandler: goldmark
[markup]
defaultMarkdownHandler = 'goldmark'
{
"markup": {
"defaultMarkdownHandler": "goldmark"
}
}
扩展名为 .md、.mdown 或 .markdown 的文件将作为 Markdown 处理，前提是您没有在 front matter 中使用 markup 字段指定不同的内容格式。
要为 Markdown 文件使用不同的渲染器，请在您的站点配置中指定 asciidocext、org、pandoc 或 rst 中的一个。
| defaultMarkdownHandler | 描述 |
|---|---|
asciidocext |
AsciiDoc |
goldmark |
Goldmark |
org |
Emacs Org 模式 |
pandoc |
Pandoc |
rst |
reStructuredText |
要使用 AsciiDoc、Pandoc 或 reStructuredText，您必须安装相关的渲染器并更新您的安全策略。
Goldmark
这是 Goldmark Markdown 渲染器的默认配置
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 扩展
默认启用以下扩展，不包括 Extras 和 Passthrough。
| 扩展 | 文档 | 已启用 |
|---|---|---|
| cjk | Goldmark 扩展：CJK | ✔️ |
| definitionList | PHP Markdown Extra：定义列表 | ✔️ |
| extras | Hugo Goldmark 扩展：Extras | |
| footnote | PHP Markdown Extra：脚注 | ✔️ |
| linkify | GitHub Flavored Markdown：自动链接 | ✔️ |
| passthrough | Hugo Goldmark 扩展：直通 | |
| strikethrough | GitHub Flavored Markdown：删除线 | ✔️ |
| table | GitHub Flavored Markdown：表格 | ✔️ |
| taskList | GitHub Flavored Markdown：任务列表项 | ✔️ |
| typographer | Goldmark 扩展：排版器 | ✔️ |
Extras
v0.126.0 中的新增功能在 Markdown 中启用 删除文本、插入文本、标记文本、下标 和 上标 元素。
| 元素 | Markdown | 渲染 |
|---|---|---|
| 删除文本 | ~~foo~~ |
<del>foo</del> |
| 插入文本 | ++bar++ |
<ins>bar</ins> |
| 标记文本 | ==baz== |
<mark>baz</mark> |
| 下标 | H~2~O |
H<sub>2</sub>O |
| 上标 | 1^st^ |
1<sup>st</sup> |
为了避免在启用 Hugo Goldmark Extras 下标扩展时发生冲突，如果您想同时渲染下标和删除线文本，您必须
- 禁用 Goldmark 删除线扩展
- 启用 Hugo Goldmark Extras 删除扩展
例如
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
}
}
}
}
直通
v0.122.0 中的新增功能启用直通扩展，以便使用 LaTeX 或 TeX 排版语法在 Markdown 中包含数学方程式和表达式。有关详细信息，请参阅 Markdown 中的数学。
排版器
排版器扩展将某些字符组合替换为如下指定的 HTML 实体
| Markdown | 替换为 | 描述 |
|---|---|---|
... |
… |
水平省略号 |
' |
’ |
撇号 |
-- |
– |
短破折号 |
--- |
— |
长破折号 |
« |
« |
左尖引号 |
“ |
“ |
左双引号 |
‘ |
‘ |
左单引号 |
» |
» |
右尖引号 |
” |
” |
右双引号 |
’ |
’ |
右单引号 |
Goldmark 设置详解
以上大多数 Goldmark 设置都是不言自明的，但有些需要解释一下。
duplicateResourceFiles
v0.123.0 版本新增（bool）如果为 true，则多语种单主机站点上的共享页面资源将为每种语言复制一份。详情请参阅多语种页面资源。默认值为 false。
parser.wrapStandAloneImageWithinParagraph
（bool）如果为 true，则在渲染时，没有相邻内容的图像元素将被包装在 p 元素中。这是默认的 Markdown 行为。当使用图像渲染钩子将独立图像渲染为 figure 元素时，设置为 false。默认值为 true。
parser.autoHeadingIDType
（string）用于自动生成标题 id 属性的策略，可以是 github、github-ascii 或 blackfriday 中的一个。
github生成与 GitHub 兼容的id属性github-ascii在重音规范化后删除任何非 ASCII 字符blackfriday生成与 Blackfriday Markdown 渲染器兼容的id属性
这也是anchorize模板函数使用的策略。默认值为 github。
parser.attribute.block
（bool）如果为 true，则为块元素启用Markdown 属性。默认值为 false。
parser.attribute.title
（bool）如果为 true，则为标题启用Markdown 属性。默认值为 true。
renderHooks.image.enableDefault
v0.123.0 版本新增（bool）如果为 true，则启用 Hugo 的嵌入式图像渲染钩子。默认值为 false。
renderHooks.link.enableDefault
v0.123.0 版本新增（bool）如果为 true，则启用 Hugo 的嵌入式链接渲染钩子。默认值为 false。
renderer.hardWraps
（bool）如果为 true，则 Goldmark 会将段落中的换行符替换为 br 元素。默认值为 false。
renderer.unsafe
（bool）如果为 true，则 Goldmark 会渲染 Markdown 中混合的原始 HTML。除非内容在您的控制之下，否则这是不安全的。默认值为 false。
AsciiDoc
这是 AsciiDoc 渲染器的默认配置
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 设置详解
attributes
（map）一个键值对的映射，每个键值对都是一个文档属性。请参阅 Asciidoctor 的属性。
backend
（string）后端输出文件格式。默认值为 html5。
extensions
（string array）一个已启用的扩展数组，可以是一个或多个 asciidoctor-html5s、asciidoctor-bibtex、asciidoctor-diagram、asciidoctor-interdoc-reftext、asciidoctor-katex、asciidoctor-latex、asciidoctor-mathematical 或 asciidoctor-question。
failureLevel
（string）触发非零退出代码（失败）的最低日志级别。默认值为 fatal。
noHeaderOrFooter
（bool）如果为 true，则输出一个可嵌入的文档，其中不包含标题、页脚以及文档正文之外的所有内容。默认值为 true。
preserveTOC
（bool）如果为 true，则保留 Asciidoctor 渲染的目录 (TOC)。默认情况下，为了使目录与现有主题兼容，Hugo 会删除 Asciidoctor 渲染的目录。要渲染目录，请在模板中使用 Page 对象上的TableOfContents方法。默认值为 false。
safeMode
（string）安全模式级别，可以是 unsafe、safe、server 或 secure 中的一个。默认值为 unsafe。
sectionNumbers
（bool）如果为 true，则为每个节标题编号。默认值为 false。
trace
(bool) 如果为 true，则在错误中包含回溯信息。默认为 false。
verbose
(bool) 如果为 true，则会将处理信息和配置文件检查详细地打印到 stderr。默认为 false。
workingFolderCurrent
(bool) 如果为 true，则将工作目录设置为与正在处理的 AsciiDoc 文件相同，允许 包含 使用相对路径。设置为 true 以使用 asciidoctor-diagram 扩展渲染图表。默认为 false。
AsciiDoc 配置示例
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 语法高亮
请按照以下步骤启用语法高亮。
- 步骤 1
- 在您的站点配置中设置
source-highlighter属性。例如
markup:
asciidocExt:
attributes:
source-highlighter: rouge
[markup]
[markup.asciidocExt]
[markup.asciidocExt.attributes]
source-highlighter = 'rouge'
{
"markup": {
"asciidocExt": {
"attributes": {
"source-highlighter": "rouge"
}
}
}
}
- 步骤 2
- 生成高亮器 CSS。例如
rougify style monokai.sublime > assets/css/syntax.css
- 步骤 3
- 在您的基本模板中添加指向 CSS 文件的链接
<head>
...
{{ with resources.Get "css/syntax.css" }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
...
</head>然后将要高亮的代码添加到您的标记中
[#hello,ruby]
----
require 'sinatra'
get '/hi' do
"Hello World!"
end
----
AsciiDoc 故障排除
运行 hugo --logLevel debug 来检查 Hugo 对 Asciidoctor 可执行文件的调用
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
这是默认的 highlight 配置。请注意，其中一些设置可以针对每个代码块进行设置，请参阅语法高亮。
markup:
highlight:
anchorLineNos: false
codeFences: true
guessSyntax: false
hl_Lines: ""
hl_inline: false
lineAnchors: ""
lineNoStart: 1
lineNos: false
lineNumbersInTable: true
noClasses: true
style: monokai
tabWidth: 4
wrapperClass: highlight
[markup]
[markup.highlight]
anchorLineNos = false
codeFences = true
guessSyntax = false
hl_Lines = ''
hl_inline = false
lineAnchors = ''
lineNoStart = 1
lineNos = false
lineNumbersInTable = true
noClasses = true
style = 'monokai'
tabWidth = 4
wrapperClass = 'highlight'
{
"markup": {
"highlight": {
"anchorLineNos": false,
"codeFences": true,
"guessSyntax": false,
"hl_Lines": "",
"hl_inline": false,
"lineAnchors": "",
"lineNoStart": 1,
"lineNos": false,
"lineNumbersInTable": true,
"noClasses": true,
"style": "monokai",
"tabWidth": 4,
"wrapperClass": "highlight"
}
}
}
对于 style，请参阅这些图库
对于 CSS，请参阅生成语法高亮器 CSS。
目录
这是目录的默认配置，适用于 Goldmark 和 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) 小于此值的标题级别将从目录中排除。例如，要从目录中排除 h1 元素，请将此值设置为 2。默认为 2。
endLevel
(int) 大于此值的标题级别将从目录中排除。例如，要从目录中排除 h4、h5 和 h6 元素，请将此值设置为 3。默认为 3。
ordered
(bool) 如果为 true，则生成有序列表而不是无序列表。默认为 false。