HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
GETTING STARTED FUNDAMENTALS

配置标记

配置标记渲染为HTML。

默认处理器

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,必须安装相关的渲染器并更新您的 安全策略 。

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

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: '’'
        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 扩展: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 下标扩展时发生冲突,如果您想同时渲染下标和删除线文本,则必须:

  1. 禁用 Goldmark 删除线扩展
  2. 启用 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 替换为 描述
... &hellip; 水平省略号
' &rsquo; 撇号
-- &ndash; 短破折号
--- &mdash; 长破折号
« &laquo; 左角引号
“ &ldquo; 左双引号
‘ &lsquo; 左单引号
» &raquo; 右角引号
” &rdquo; 右双引号
’ &rsquo; 右单引号

Goldmark 设置说明

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

duplicateResourceFiles
New in v0.123.0

(bool) 如果为 true ,则多语言单主机站点上的共享页面资源将为每种语言复制一份。有关详细信息,请参阅 多语言页面资源 。默认为 false 。

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

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 中的一种或多种。

为减轻安全风险,扩展名数组中的条目可能不包含正斜杠 (/)、反斜杠 () 或句点。由于此限制,扩展名必须位于 Ruby 的 $LOAD_PATH 中。

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 和 Asciidoctor:

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

(int) 小于此值的标题级别将从目录中排除。例如,要从目录中排除 h1 元素,请将此值设置为 2 。默认为 2 。

endLevel

(int) 大于此值的标题级别将从目录中排除。例如,要从目录中排除 h4 、 h5 和 h6 元素,请将此值设置为 3 。默认为 3 。

ordered

(bool) 如果为 true ,则生成有序列表而不是无序列表。默认为 false 。

See also

  • 内容格式
  • Markdown 属性
  • 短代码
  • Passthrough
  • 代码块

On this page

  • 默认处理器
  • Goldmark
  • AsciiDoc
  • 高亮显示
  • 目录
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护