配置标记

默认处理器

Hugo 使用 Goldmark 将 Markdown 渲染为 HTML。

hugo.

markup:
  defaultMarkdownHandler: goldmark

[markup]
  defaultMarkdownHandler = 'goldmark'

{
   "markup": {
      "defaultMarkdownHandler": "goldmark"
   }
}

如果前置内容的 markup 字段中未指定不同的内容格式，则扩展名为 .md 、 .mdown 或 .markdown 的文件将被处理为 Markdown。

要为 Markdown 文件使用不同的渲染器，请在站点配置中指定 asciidocext 、 org 、 pandoc 或 rst 之一。

defaultMarkdownHandler	描述
`asciidocext`	AsciiDoc
`goldmark`	Goldmark
`org`	Emacs Org Mode
`pandoc`	Pandoc
`rst`	reStructuredText

要使用 AsciiDoc、Pandoc 或 reStructuredText，必须安装相关的渲染器并更新您的安全策略。

Goldmark

这是 Goldmark Markdown 渲染器的默认配置：

hugo.

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: '&rsquo;'
        disable: false
        ellipsis: '&hellip;'
        emDash: '&mdash;'
        enDash: '&ndash;'
        leftAngleQuote: '&laquo;'
        leftDoubleQuote: '&ldquo;'
        leftSingleQuote: '&lsquo;'
        rightAngleQuote: '&raquo;'
        rightDoubleQuote: '&rdquo;'
        rightSingleQuote: '&rsquo;'
    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 = '&rsquo;'
        disable = false
        ellipsis = '&hellip;'
        emDash = '&mdash;'
        enDash = '&ndash;'
        leftAngleQuote = '&laquo;'
        leftDoubleQuote = '&ldquo;'
        leftSingleQuote = '&lsquo;'
        rightAngleQuote = '&raquo;'
        rightDoubleQuote = '&rdquo;'
        rightSingleQuote = '&rsquo;'
    [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 扩展：Passthrough
strikethrough	GitHub Flavored Markdown：删除线	✔️
table	GitHub Flavored Markdown：表格	✔️
taskList	GitHub Flavored Markdown：任务列表项	✔️
typographer	Goldmark 扩展：排版	✔️

Extras

New in 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 删除扩展

例如：

hugo.

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.0

启用 passthrough 扩展可以使用 LaTeX 或 TeX 排版语法在 Markdown 中包含数学方程式和表达式。有关详细信息，请参阅 Markdown 中的数学。

Typographer

Typographer 扩展将某些字符组合替换为 HTML 实体，如下所示：

Markdown	替换为	描述
`...`	`…`	水平省略号
`'`	`’`	撇号
`--`	`–`	短破折号
`---`	`—`	长破折号
`«`	`«`	左角引号
`“`	`“`	左双引号
`‘`	`‘`	左单引号
`»`	`»`	右角引号
`”`	`”`	右双引号
`’`	`’`	右单引号

Goldmark 设置说明

上面大多数 Goldmark 设置是不言自明的，但有些需要解释。

duplicateResourceFiles

New in 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

New in v0.123.0

(bool) 如果为 true ，则启用 Hugo 的嵌入式图像渲染钩子。默认为 false 。

renderHooks.link.enableDefault

New in v0.123.0

(bool) 如果为 true ，则启用 Hugo 的嵌入式链接渲染钩子。默认为 false 。

renderer.hardWraps

(bool) 如果为 true ，则 Goldmark 会将段落中的换行符替换为 br 元素。默认为 false 。

renderer.unsafe

(bool) 如果为 true ，则 Goldmark 会渲染 Markdown 中混合的原始 HTML。除非内容受您控制，否则这是不安全的。默认为 false 。

AsciiDoc

这是 AsciiDoc 渲染器的默认配置：

hugo.

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)。默认情况下，为了使 TOC 与现有主题兼容，Hugo 会删除 Asciidoctor 渲染的 TOC。要渲染 TOC，请在模板中使用 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 配置示例

hugo.

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 属性。例如：

hugo.

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 文件的链接：

layouts/_default/baseof.html

<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 配置。请注意，其中一些设置可以针对每个代码块进行设置，请参阅语法高亮。

hugo.

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
    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
    noHl = false
    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,
         "noHl": false,
         "style": "monokai",
         "tabWidth": 4,
         "wrapperClass": "highlight"
      }
   }
}

对于 style ，请参阅以下图库：

对于 CSS，请参阅生成语法高亮器 CSS 。

默认处理器

Goldmark

Goldmark 扩展

Extras

Passthrough

Typographer

Goldmark 设置说明

duplicateResourceFiles

parser.wrapStandAloneImageWithinParagraph

parser.autoHeadingIDType

parser.attribute.block

parser.attribute.title

renderHooks.image.enableDefault

renderHooks.link.enableDefault

renderer.hardWraps

renderer.unsafe

AsciiDoc

AsciiDoc 设置说明

attributes

backend

extensions

failureLevel

noHeaderOrFooter

preserveTOC

safeMode

sectionNumbers

trace

verbose

workingFolderCurrent

AsciiDoc 配置示例

AsciiDoc 语法高亮

AsciiDoc 故障排除

高亮显示

目录

startLevel

endLevel

ordered

See also

Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)