Hugo 配置标记

Hugo 配置标记。

默认处理器

在默认配置中，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 Mode
`pandoc`	Pandoc
`rst`	reStructuredText

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

除非您需要替代 Markdown 处理器提供的独特功能，否则我们强烈建议您使用默认设置。Goldmark 速度快、维护良好、符合 CommonMark 规范，并与 GitHub Flavored Markdown (GFM) 兼容。

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:
        backlinkHTML: '&#x21a9;&#xfe0e;'
        enable: true
        enableAutoIDPrefix: false
      linkify: true
      linkifyProtocol: https
      passthrough:
        delimiters:
          block: &block
[]
          inline: &block *block
        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
      autoDefinitionTermID: false
      autoHeadingID: true
      autoIDType: github
      wrapStandAloneImageWithinParagraph: true
    renderHooks:
      image:
        enableDefault: false
        useEmbedded: auto
      link:
        enableDefault: false
        useEmbedded: auto
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false

[markup]
  [markup.goldmark]
    duplicateResourceFiles = false
    [markup.goldmark.extensions]
      definitionList = 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.footnote]
        backlinkHTML = '&#x21a9;&#xfe0e;'
        enable = true
        enableAutoIDPrefix = 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]
      autoDefinitionTermID = false
      autoHeadingID = true
      autoIDType = 'github'
      wrapStandAloneImageWithinParagraph = true
      [markup.goldmark.parser.attribute]
        block = false
        title = true
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        enableDefault = false
        useEmbedded = 'auto'
      [markup.goldmark.renderHooks.link]
        enableDefault = false
        useEmbedded = 'auto'
    [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": {
               "backlinkHTML": "\u0026#x21a9;\u0026#xfe0e;",
               "enable": true,
               "enableAutoIDPrefix": false
            },
            "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
            },
            "autoDefinitionTermID": false,
            "autoHeadingID": true,
            "autoIDType": "github",
            "wrapStandAloneImageWithinParagraph": true
         },
         "renderHooks": {
            "image": {
               "enableDefault": false,
               "useEmbedded": "auto"
            },
            "link": {
               "enableDefault": false,
               "useEmbedded": "auto"
            }
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

扩展

下面的扩展中，除了 Extras 和 Passthrough 外，默认都启用。

扩展	文档	启用
`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.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>`

为避免冲突¹，如果您启用 Extras 扩展的"下标"功能，则必须禁用 Strikethrough 扩展：

markup:
  goldmark:
    extensions:
      extras:
        subscript:
          enable: true
      strikethrough: false

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      strikethrough = false
      [markup.goldmark.extensions.extras]
        [markup.goldmark.extensions.extras.subscript]
          enable = true

{
   "markup": {
      "goldmark": {
         "extensions": {
            "extras": {
               "subscript": {
                  "enable": true
               }
            },
            "strikethrough": false
         }
      }
   }
}

如果在禁用 Strikethrough 扩展后仍需要显示删除文本，请启用 Extras 扩展的"删除文本"功能：

markup:
  goldmark:
    extensions:
      extras:
        delete:
          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": {
               "delete": {
                  "enable": true
               }
            },
            "strikethrough": false
         }
      }
   }
}

使用此配置，要格式化删除文本，请使用双波浪号包裹。

Footnote

默认启用，Footnote 扩展允许在 Markdown 中包含脚注。

enable: New in v0.151.0; (bool) 是否启用 Footnotes 扩展。默认值是 true。
backlinkHTML: New in v0.151.0; (string) 在脚注末尾显示的 HTML，将用户链接回正文中相应的引用。默认值是 ↩︎（返回箭头符号）。
enableAutoIDPrefix: New in v0.151.0; (bool) 是否在脚注 ID 前添加唯一前缀，防止多个文档一起渲染时发生冲突。此前缀对每个逻辑路径是唯一的，这意味着前缀在不同内容维度（如语言）之间不是唯一的。默认值是 false。

Passthrough

启用 Passthrough 扩展以在 Markdown 中使用 LaTeX 标记包含数学方程和表达式。详见 Markdown 中的数学。

Typographer

Typographer 扩展将某些字符组合替换为如下指定的 HTML 实体：

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

Goldmark 设置说明

大多数 Goldmark 设置是不言自明的，但有些需要说明。

duplicateResourceFiles

(bool) 是否在多语言单主机站点上为每种语言复制共享页面资源。详见多语言页面资源。默认值是 false。

对于多语言单主机站点，将此参数设置为 false 将启用 Hugo 的嵌入式链接渲染钩子和嵌入式图片渲染钩子。这是多语言单主机站点的默认配置。

parser.wrapStandAloneImageWithinParagraph

(bool) 是否在渲染时将没有相邻内容的图片元素包裹在 p 元素中。这是默认 Markdown 行为。当使用图片渲染钩子将独立图片渲染为 figure 元素时设置为 false。默认值是 true。

parser.autoDefinitionTermID

New in v0.144.0

(bool) 是否自动为描述列表术语（即 dt 元素）添加 id 属性。当为 true 时，每个 dt 元素的 id 属性可通过 Page 对象上的 Fragments.Identifiers 方法访问。

parser.autoHeadingID

(bool) 是否自动为标题（即 h1、h2、h3、h4、h5 和 h6 元素）添加 id 属性。

parser.autoIDType

(string) 自动生成 id 属性的策略，github、github-ascii 或 blackfriday 之一。默认值是 github。

github: 生成与 GitHub 兼容的 id 属性
github-ascii: 在重音标准化后删除任何非 ASCII 字符
blackfriday: 生成与 Blackfriday Markdown 渲染器兼容的 id 属性

这也是 anchorize 模板函数使用的策略。

parser.attribute.block

(bool) 是否为块元素启用 Markdown 属性。默认值是 false。

parser.attribute.title

(bool) 是否为标题启用 Markdown 属性。默认值是 true。

renderHooks.image.enableDefault

在 v0.148.0 中弃用。改用 renderHooks.image.useEmbedded。

renderHooks.image.useEmbedded

New in v0.148.0

(string) 何时使用嵌入式图片渲染钩子。auto、never、always 或 fallback 之一。默认值是 auto。

auto: 仅对禁用了共享页面资源复制功能的多语言单主机项目使用嵌入式图片渲染钩子。如果您的项目、模块或主题定义了自定义图片渲染钩子，则将使用这些钩子。
never: 从不使用嵌入式图片渲染钩子。如果您的项目、模块或主题定义了自定义图片渲染钩子，则将使用这些钩子。
always: 始终使用嵌入式图片渲染钩子，即使您的项目、模块或主题提供了自定义图片渲染钩子。
fallback: 仅当您的项目、模块或主题未提供自定义图片渲染钩子时使用嵌入式图片渲染钩子。如果存在自定义图片渲染钩子，则将使用这些钩子。

renderHooks.link.enableDefault

在 v0.148.0 中弃用。改用 renderHooks.link.useEmbedded。

renderHooks.link.useEmbedded

(string) 何时使用嵌入式链接渲染钩子。auto、never、always 或 fallback 之一。默认值是 auto。

auto: 仅对禁用了共享页面资源复制功能的多语言单主机项目使用嵌入式链接渲染钩子。如果您的项目、模块或主题定义了自定义链接渲染钩子，则将使用这些钩子。
never: 从不使用嵌入式链接渲染钩子。如果您的项目、模块或主题定义了自定义链接渲染钩子，则将使用这些钩子。
always: 始终使用嵌入式链接渲染钩子，即使您的项目、模块或主题提供了自定义链接渲染钩子。
fallback: 仅当您的项目、模块或主题未提供自定义链接渲染钩子时使用嵌入式链接渲染钩子。如果存在自定义链接渲染钩子，则将使用这些钩子。

renderer.hardWraps

(bool) 是否将段落内的换行符替换为 br 元素。默认值是 false。

renderer.unsafe

(bool) 是否渲染 Markdown 中混合的原始 HTML。除非内容在您的控制之下，否则这是不安全的。默认值是 false。

AsciiDoc

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

markup:
  asciidocExt: null

[markup]

{
   "markup": {
      "asciidocExt": null
   }
}

AsciiDoc 设置说明

attributes: (map) 键值对映射，每个都是文档属性。详见 Asciidoctor 的属性。
backend: (string) 后端输出文件格式。默认值是 html5。
extensions: ([]string) 启用扩展的数组，如 asciidoctor-html5s、asciidoctor-bibtex 或 asciidoctor-diagram。

为了减轻安全风险，扩展数组中的条目不能包含正斜杠 (/)、反斜杠 (\) 或句点。由于此限制，扩展必须在 Ruby 的 $LOAD_PATH 中。
failureLevel: (string) 触发非零退出代码（失败）的最小日志记录级别。默认值是 fatal。
noHeaderOrFooter: (bool) 是否输出可嵌入文档，不包括文档的头部、尾部和正文之外的所有内容。默认值是 true。
preserveTOC: (bool) 是否保留 Asciidoctor 渲染的目录 (TOC)。默认情况下，为了使 TOC 与现有主题兼容，Hugo 会移除 Asciidoctor 渲染的 TOC。要渲染 TOC，在模板中使用 Page 对象上的 TableOfContents 方法。默认值是 false。
safeMode: (string) 安全模式级别，unsafe、safe、server 或 secure 之一。默认值是 unsafe。
sectionNumbers: (bool) 是否为每个章节标题编号。默认值是 false。
trace: (bool) 是否在错误时包含回溯信息。默认值是 false。
verbose: (bool) 是否详细打印处理信息和配置文件检查到 stderr。默认值是 false。
workingFolderCurrent: (bool) 是否将工作目录设置为与正在处理的 AsciiDoc 文件相同，允许包含使用相对路径。设置为 true 以使用 asciidoctor-diagram 扩展渲染图表。默认值是 false。

配置示例

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
      }
   }
}

语法高亮

按照以下步骤启用语法高亮。

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

layouts/baseof.html

<head>
  ...
  {{ with resources.Get "css/syntax.css" }}
    <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
  {{ end }}
  ...
</head>

步骤 4

在标记中添加要高亮的代码：

[#hello,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----

故障排除

运行 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

这是默认配置。

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"
      }
   }
}

anchorLineNos

(bool) 是否将每个行号渲染为 HTML 锚元素，将周围 span 元素的 id 属性设置为行号。如果 lineNos 为 false，则此选项无关。默认为 false。

codeFences

(bool) 是否高亮代码围栏。默认为 true。

guessSyntax

(bool) 如果 LANG 参数为空或设置为没有相应词法分析器的语言，是否自动检测语言。如果无法自动检测语言，则回退到纯文本词法分析器。默认为 false。

Chroma 语法高亮器包含约 250 种语言的词法分析器，但其中只有 5 种实现了自动语言检测。

hl_Lines

(string) 要在高亮代码中强调的行的空格分隔列表。要强调第 2、3、4 和 7 行，将此值设置为 2-4 7。此选项独立于 lineNoStart 选项。

hl_inline

(bool) 是否在没有包装容器的情况下渲染高亮代码。默认为 false。

lineAnchors

(string) 在将行号渲染为 HTML 锚元素时，将此值前置到周围 span 元素的 id 属性。当页面包含两个或更多代码块时，这提供了唯一的 id 属性。如果 lineNos 或 anchorLineNos 为 false，则此选项无关。

lineNoStart

(int) 在第一行显示的数字。如果 lineNos 为 false，则此选项无关。默认为 1。

lineNos

(any) 控制行号显示。默认为 false。

true：启用行号，由 lineNumbersInTable 控制。
false：禁用行号。
inline：启用内联行号（将 lineNumbersInTable 设置为 false）。
table：启用基于表格的行号（将 lineNumbersInTable 设置为 true）。

lineNumbersInTable

(bool) 是否在 HTML 表格中渲染高亮代码，包含两个单元格。左表格单元格包含行号，右表格单元格包含代码。如果 lineNos 为 false，则此选项无关。默认为 true。

noClasses

(bool) 是否使用内联 CSS 样式而不是外部 CSS 文件。默认为 true。要使用外部 CSS 文件，将此值设置为 false 并从命令行生成 CSS 文件：

hugo gen chromastyles --style=monokai > syntax.css

style

(string) 应用于高亮代码的 CSS 样式。区分大小写。默认为 monokai。请参阅语法高亮样式。

tabWidth

(int) 用此数量的空格替换高亮代码中的每个制表符。如果 noClasses 为 false，则此选项无关。默认为 4。

wrapperClass

New in v0.140.2

(string) 用于高亮代码最外层元素的类。默认为 highlight。

startLevel: (int) 小于此值的标题级别将从目录中排除。例如，要从目录中排除 h1 元素，将此值设置为 2。默认值是 2。
endLevel: (int) 大于此值的标题级别将从目录中排除。例如，要从目录中排除 h4、h5 和 h6 元素，将此值设置为 3。默认值是 3。
ordered: (bool) 是否生成有序列表而不是无序列表。默认值是 false。

详见详情。 ↩︎

Last updated: January 1, 0001

Improve this page