入门 基础知识

配置标记语言

默认处理器

默认情况下，Hugo使用 Goldmark 将标记转换为HTML。

hugo.
      
markup:
  defaultMarkdownHandler: goldmark

[markup]
  defaultMarkdownHandler = 'goldmark'

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

以 .md 或 .markdown 扩展名的文件将被解析为标记语言文件，前提是您在前置元数据中没有指定不同的 content format 。 要为标记语言文件使用其他渲染器，请在站点配置中指定以下之一：asciidocext、org、pandoc 或 rst 。

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

要使用 Asciidoc、Pandoc 或 reStructuredText，您必须安装相应的渲染器并更新您的 security policy。

Goldmark

这是 Goldmark 标记语言渲染器的默认配置：

hugo.
      
markup:
  goldmark:
    extensions:
      cjk:
        eastAsianLineBreaks: false
        eastAsianLineBreaksStyle: simple
        enable: false
        escapedSpace: false
      definitionList: true
      footnote: true
      linkify: true
      linkifyProtocol: https
      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
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false

[markup]
  [markup.goldmark]
    [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.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.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false

{
   "markup": {
      "goldmark": {
         "extensions": {
            "cjk": {
               "eastAsianLineBreaks": false,
               "eastAsianLineBreaksStyle": "simple",
               "enable": false,
               "escapedSpace": false
            },
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "linkifyProtocol": "https",
            "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
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

有关扩展的详细信息，请参阅 Goldmark 文档的此部分。

以下是一些设置的解释：

hardWraps
默认情况下，Goldmark 忽略段落内的换行。设置为 true 以将换行渲染为 <br> 元素。
unsafe
默认情况下，Goldmark 不会渲染原始 HTML 和潜在危险链接。如果您有大量的内联 HTML 和/或 JavaScript，则可能需要打开此选项。
typographer
typographer 扩展将以下字符组合替换为指定的 HTML 实体：
Markdown 替换为 说明
... &hellip; 水平省略号
' &rsquo; 单引号
-- &ndash; 短破折号
--- &mdash; 长破折号
« &laquo; 左角引号
“ &ldquo; 左双引号
‘ &lsquo; 左单引号
» &raquo; 右角引号
” &rdquo; 右双引号
’ &rsquo; 右单引号
attribute
通过在 Markdown 元素后面的同一行上使用大括号（例如{.myclass class="class1 class2" }）和在新行上使用大括号（例如 -{.fruits}）来启用标题和块的自定义属性支持。

Hugo 支持为 Markdown 块（例如表格、列表、段落等）添加属性（例如 CSS 类）。

带有 CSS 类的引用块：

> foo
> bar
{.myclass}

以下是当前一些限制：对于表格，您目前只能将其应用于整个表格；对于列表，只能将其应用于 ul/ol 节点，例如：

* 水果
  * 苹果
  * 橘子
  * 香蕉
{.fruits}
* 乳制品
  * 牛奶
  * 奶酪
{.dairies}
{.list}

注意，在代码块中的属性必须放在开标签后面，与任何其他突出显示处理指令一起使用，例如：

```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```
autoHeadingIDType (“github”)
用于创建自动ID（锚点名称）的策略。可用类型有 github、github-ascii 和 blackfriday。github 生成与 GitHub 兼容的 ID，github-ascii 在重音规范化后删除任何非 ASCII 字符，并且 blackfriday 将使 ID 与 Hugo 0.60 之前的默认标记语言引擎 Blackfriday 兼容。请注意，如果 Goldmark 是您的默认标记语言引擎，则这也是 anchorize 模板函数使用的策略。

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
      }
   }
}
attributes
（map）这是您的 AsciiDoc 文件中引用的变量列表。这是一个变量名称/值映射的列表。有关详细信息，请参阅 Asciidoctor 的 attributes。
backend:
（string）除非您知道自己在做什么，请不要更改此项。
extensions
（[]string）可能的扩展有 asciidoctor-html5s、asciidoctor-bibtex、asciidoctor-diagram、asciidoctor-interdoc-reftext、asciidoctor-katex、asciidoctor-latex、asciidoctor-mathematical 和 asciidoctor-question。
failureLevel
（string）触发非零退出代码（失败）的的最低日志级别。
noHeaderOrFooter
（bool）输出一个可嵌入的文档，不包括头部、尾部和文档主体外的任何内容。除非您知道自己在做什么，请不要更改此项。
preserveTOC
（bool）默认情况下，Hugo 删除 Asciidoctor 生成的目录并通过内置变量 .TableOfContents 提供该目录，以便进行进一步的自定义并与各种 Hugo 主题更好地集成。可以将此选项设置为 true 以保留 Asciidoctor 生成的目录。
safeMode
（string）安全模式级别 unsafe、safe、server 或 secure。除非您知道自己在做什么，请不要更改此项。
sectionNumbers
（bool）自动编号节标题。
trace
（bool）在错误时包含回溯信息。
verbose
（bool）详细打印处理信息和配置文件检查到 stderr。
workingFolderCurrent
（bool）将工作目录设置为与正在处理的 AsciiDoc 文件相同，以便使用相对路径进行 include。此设置使用 asciidoctor cli 参数 –base-dir 和 attribute outdir。对于使用 asciidoctor-diagram 渲染图表，必须将 workingFolderCurrent 设置为 true。

请注意，基于安全考虑，只允许没有路径分隔符（\、/ 或 .）的扩展名。这意味着扩展只能在 Ruby 的 $LOAD_PATH 中（即可能是用户安装的扩展）。任何相对于网站路径声明的扩展将不会被接受。

设置扩展和属性的示例：

[markup.asciidocExt]
    extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
    workingFolderCurrent = true
    [markup.asciidocExt.attributes]
        my-base-url = "https://example.com/"
        my-attribute-name = "my value"

在复杂的 Asciidoctor 环境中，精确调试您的外部帮助程序的具体调用和所有参数非常有帮助。使用 -v 在运行 Hugo 时，您将获得如下输出：

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

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

有关 style，请参阅这些图库：

有关 CSS，请参阅 生成语法高亮器CSS。

目录

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

这些设置仅适用于 Goldmark 渲染器：

startLevel
要开始渲染目录的标题级别，值从 1 (h1) 开始。
endLevel
要停止渲染目录的标题级别，包括该级别。
ordered
如果为 true，则生成有序列表而不是无序列表。

渲染钩子

请参阅 Markdown 渲染钩子。

See also

Last updated: November 23, 2023: first release (332dc4cd7)
Improve this page