Hugo Markup 配置完全指南从 Goldmark 到 AsciiDoc、reStructuredText 与代码高亮【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo导读markup是 Hugo 站点构建中控制内容如何被渲染为 HTML的核心配置区块。本文以官方文档 docs/content/en/configuration/markup.md 为骨架结合本仓库源码markup/markup_config/config.go、markup/goldmark/goldmark_config/config.go、markup/asciidocext/asciidocext_config/config.go 等逐项讲解默认 Markdown 处理器、Goldmark 扩展与解析器设置、AsciiDoc / reStructuredText 外部渲染器的接入方式、代码高亮与目录TOC配置。读完本文你将能按需切换 Markdown 处理器、启用脚注 / LaTeX 数学 / 排版替换等扩展并为 AsciiDoc 与 reStructuredText 配置语法高亮所有配置均可在hugo.toml中直接落地。默认处理器Default handlerHugo 默认使用 [Goldmark][] 将 Markdown 渲染为 HTML对应配置为[markup] defaultMarkdownHandler goldmark从源码看该默认值定义在 markup/markup_config/config.go 的Default结构体中DefaultMarkdownHandler: goldmark并在 markup/markup.go 的NewConverterProvider中完成转换器注册与别名绑定当某个转换器的名称与defaultMarkdownHandler匹配时会额外注册markdown别名确保markdown始终指向当前默认处理器。以.md、.mdown或.markdown结尾的文件默认按 Markdown 处理除非你在 front matter 中通过markup字段显式指定其他格式。切换渲染器可在项目配置中将defaultMarkdownHandler指定为以下任一值defaultMarkdownHandler渲染器asciidocext[AsciiDoc][]goldmark[Goldmark][]org[Emacs Org Mode][]pandoc[Pandoc][]rst[reStructuredText][]使用 AsciiDoc、Pandoc 或 reStructuredText 时你必须先安装对应的外部渲染器Asciidoctor、Pandoc、Docutils并更新 security policy 以允许 Hugo 调用这些外部可执行文件——Hugo 通过 common/hexec 管理这类外部命令调用默认安全策略下外部命令是被禁止的。[!NOTE] 除非你确实需要某个替代 Markdown 处理器提供的独有能力否则强烈建议保持默认设置。Goldmark 快速、维护良好、符合 [CommonMark][] 规范并兼容 [GitHub Flavored Markdown][]GFM。从源码也能印证asciidocext、rst、pandoc、org均依赖外部可执行文件markup/markup.go 中它们与goldmark并列注册但实现路径不同。Goldmark 渲染器Goldmark 是 Hugo 内置的 Markdown 渲染引擎Go 语言实现仓库位于 markup/goldmark其默认配置如下完整默认值定义见 markup/goldmark/goldmark_config/config.go[markup.goldmark] duplicateResourceFiles false [markup.goldmark.renderer] hardWraps false unsafe false xhtml false [markup.goldmark.parser] attribute.block false attribute.title true autoHeadingID true autoIDType github autoDefinitionTermID false wrapStandAloneImageWithinParagraph true [markup.goldmark.extensions] cjk.enable false cjk.eastAsianLineBreaks false cjk.eastAsianLineBreaksStyle simple cjk.escapedSpace false definitionList true footnote.enable true footnote.enableAutoIDPrefix false footnote.backlinkHTML #x21a9;#xfe0e; linkify true linkifyProtocol https strikethrough true table true taskList true typographer.disable false typographer.ellipsis hellip; typographer.leftAngleQuote laquo; typographer.rightAngleQuote raquo; typographer.leftDoubleQuote ldquo; typographer.rightDoubleQuote rdquo; typographer.leftSingleQuote lsquo; typographer.rightSingleQuote rsquo; typographer.apostrophe rsquo; typographer.enDash ndash; typographer.emDash mdash; [markup.goldmark.extensions.extras] delete.enable false insert.enable false mark.enable false subscript.enable false superscript.enable false [markup.goldmark.extensions.passthrough] enable false [markup.goldmark.renderHooks.image] enableDefault false useEmbedded auto [markup.goldmark.renderHooks.link] enableDefault false useEmbedded auto扩展Extensions除 Extras 与 Passthrough 外其余扩展默认均启用扩展说明默认启用cjk中日韩文字排版支持✔definitionListPHP Markdown Extra 定义列表✔extrasHugo Goldmark Extensions 的 Extras 扩展删除/插入/标记/上下标否footnotePHP Markdown Extra 脚注✔linkifyGFM 自动链接✔passthroughHugo Goldmark Extensions 的 Passthrough 扩展LaTeX 数学否strikethroughGFM 删除线✔tableGFM 表格✔taskListGFM 任务列表✔typographer排版替换弯引号、破折号、省略号等✔注意cjk在配置默认值中Enable为falsemarkup/goldmark/goldmark_config/config.go但按官方文档说明它在功能层面默认启用——若你的站点以中日韩文字为主建议显式开启cjk.enable true以获得更优的换行处理。Extras删除、插入、标记与上下标Extras 扩展允许在 Markdown 中直接使用 HTML5 语义元素元素Markdown渲染结果删除文本~~foo~~delfoo/del插入文本barinsbar/ins标记文本bazmarkbaz/mark下标H~2~OHsub2/subO上标1^st^1supst/sup冲突警告由于~~同时是删除线与下标的语法若启用 Extras 的下标功能必须先禁用 Strikethrough 扩展[markup.goldmark.extensions] strikethrough false [markup.goldmark.extensions.extras.subscript] enable true禁用 Strikethrough 后若仍需删除文本效果可启用 Extras 的 delete 功能[markup.goldmark.extensions] strikethrough false [markup.goldmark.extensions.extras.delete] enable true配置后删除文本同样使用双波浪号包裹~~foo~~但由 Extras 扩展渲染为del元素而非 GFM 语义。Footnote 脚注扩展默认启用可在 Markdown 中使用[^1]语法插入脚注。其配置项包括enable: bool新增于 0.151.0是否启用脚注扩展默认true。backlinkHTML: string新增于 0.151.0脚注末尾指向正文引用的返回链接 HTML默认#x21a9;#xfe0e;↩ 返回箭头符号与源码中BacklinkHTML: #x21a9;#xfe0e;一致markup/goldmark/goldmark_config/config.go。enableAutoIDPrefix: bool新增于 0.151.0是否为脚注 ID 添加唯一前缀防止多文档合并渲染时 ID 冲突。前缀对每个逻辑路径唯一但在不同内容维度如多语言间不保证唯一默认false。需要说明的是脚注配置在 0.151.0 中由布尔值升级为结构体源码 markup/markup_config/config.go 的normalizeConfig会自动迁移旧配置footnote false会转换为footnote.enable falsefootnote true则保持默认。PassthroughLaTeX 数学公式启用 Passthrough 扩展即可在 Markdown 中使用 LaTeX 书写数学公式。配置示例[markup.goldmark.extensions.passthrough] enable true [markup.goldmark.extensions.passthrough.delimiters] block [[\[, \]], [$$, $$]] inline [[\(, \)], [$, $]]完整的数学语法说明参见 mathematics in Markdown。从源码看Passthrough 的Delimiters结构支持Inline与Block两组分隔符每组元素为「开分隔符、闭分隔符」二元组markup/goldmark/goldmark_config/config.go。Typographer 排版替换Typographer 扩展将特定字符组合替换为 HTML 实体Markdown替换为说明...hellip;水平省略号rsquo;撇号--ndash;短破折号en dash---mdash;长破折号em dash«laquo;左书名号“ldquo;左双引号‘lsquo;左单引号»raquo;右书名号”rdquo;右双引号’rsquo;右单引号所有替换值均可在配置中覆盖例如[markup.goldmark.extensions.typographer] enDash #8211; emDash #8212;源码中的默认实体值见 markup/goldmark/goldmark_config/config.go。Typographer 在 0.112.0 中也由布尔值升级为结构体旧配置typographer false会自动迁移为typographer.disable true见 markup/markup_config/config.go。设置SettingsduplicateResourceFiles: bool多语言单主机项目中是否为每种语言复制共享页面资源默认false。详见 multilingual page resources。[!NOTE] 在多语言单主机项目中将该参数设为false会启用 Hugo 的 embedded link render hook 与 embedded image render hook这也是多语言单主机项目的默认配置。parser.wrapStandAloneImageWithinParagraph: bool渲染时是否将无相邻内容的独立图片包裹在p元素内。这是标准 Markdown 行为默认true。若你使用 image render hook 将独立图片渲染为figure元素应设为false。parser.autoDefinitionTermID: bool新增于 0.144.0是否自动为描述列表术语dt元素添加id属性。为true时可通过Page对象的Fragments.Identifiers方法访问每个dt的id。默认false。源码在 markup/goldmark/goldmark_config/config.go 中做了联动约束若AutoDefinitionTermID为true但DefinitionList扩展被禁用则该设置自动失效。parser.autoHeadingID: bool是否自动为h1–h6标题添加id属性默认true。parser.autoIDType: string自动生成id的策略取值为github、github-ascii或blackfriday默认github。常量定义见 markup/goldmark/goldmark_config/config.go。github生成与 GitHub 兼容的idgithub-ascii在重音规范化后丢弃所有非 ASCII 字符blackfriday生成与 Blackfriday 渲染器兼容的id。该策略同样被urls.Anchorize函数使用。源码中AutoHeadingIDType已在 0.144.0 更名为AutoIDType旧的AutoHeadingIDType配置会被自动迁移markup/goldmark/goldmark_config/config.go。parser.attribute.block: bool是否启用块级元素 Markdown 属性默认false。parser.attribute.title: bool是否启用标题的 Markdown 属性默认true。renderHooks.image.enableDefault: bool已在 0.148.0 弃用请改用renderHooks.image.useEmbedded。renderHooks.image.useEmbedded: string新增于 0.148.0何时使用 embedded image render hook取值为auto、never、always或fallback默认auto。auto仅在多语言单主机项目且禁用共享页面资源复制时使用内嵌图片渲染钩子若项目、模块或主题定义了自定义图片渲染钩子则优先使用自定义钩子。never永不使用内嵌图片渲染钩子有自定义钩子时使用自定义钩子。always总是使用内嵌图片渲染钩子即使存在自定义钩子。fallback仅在不存在自定义图片渲染钩子时使用内嵌钩子。renderHooks.link.enableDefault: bool已在 0.148.0 弃用请改用renderHooks.link.useEmbedded。renderHooks.link.useEmbedded: string何时使用 embedded link render hook取值与默认值同上auto/never/always/fallback默认auto各取值的语义与图片渲染钩子一致。useEmbedded常量在 markup/goldmark/goldmark_config/config.go 中定义。renderer.hardWraps: bool是否将段落内的换行符替换为br元素默认false。renderer.unsafe: bool是否渲染 Markdown 中混写的原始 HTML默认false。除非内容完全受你控制否则开启是不安全的。对应源码字段 markup/goldmark/goldmark_config/config.go 中还有xhtml输出 XHTML 而非 HTML5选项。AsciiDoc 渲染器使用asciidocext时Hugo 会调用外部的 Asciidoctor 可执行文件在 Windows 上为asciidoctor.bat。其默认配置见 markup/asciidocext/asciidocext_config/config.go如下[markup.asciidocExt] attributes {} backend html5 extensions [] failureLevel fatal noHeaderOrFooter true preserveTOC false safeMode unsafe sectionNumbers false trace false verbose false workingFolderCurrent false设置attributes: map键值对集合每个键值对是一个文档属性。参见 Asciidoctor 的 [attributes][] 文档。backend: string后端输出文件格式默认html5。源码 markup/asciidocext/asciidocext_config/config.go 中允许的值包括html5、html5s、xhtml5、docbook5、docbook45与manpage。extensions: []string启用的扩展数组例如asciidoctor-html5s、asciidoctor-bibtex或asciidoctor-diagram。[!NOTE] 为降低安全风险扩展名中不得包含正斜杠/、反斜杠\或句点。受此限制扩展必须位于 Ruby 的$LOAD_PATH中。failureLevel: string触发非零退出码构建失败的最低日志级别默认fatal。源码 markup/asciidocext/asciidocext_config/config.go 中允许fatal与warn两个级别。noHeaderOrFooter: bool是否输出可嵌入文档——即排除页眉、页脚及文档正文之外的所有内容默认true。preserveTOC: bool是否保留 Asciidoctor 渲染的目录TOC。默认情况下为兼容现有主题Hugo 会移除 Asciidoctor 渲染的 TOC如需渲染目录请在模板中使用Page对象的TableOfContents方法默认false。safeMode: string安全模式级别取值为unsafe、safe、server或secure默认unsafe。允许值在源码 markup/asciidocext/asciidocext_config/config.go 中校验。sectionNumbers: bool是否为每个章节标题编号默认false。trace: bool出错时是否包含回溯backtrace信息默认false。verbose: bool是否向 stderr 详细打印处理信息与配置文件检查结果默认false。workingFolderCurrent: bool是否将工作目录设置为与正在处理的 AsciiDoc 文件相同从而允许 [includes][] 使用相对路径。渲染 [asciidoctor-diagram][] 图表时需设为true默认false。配置示例[markup.asciidocExt] backend html5s extensions [asciidoctor-html5s,asciidoctor-diagram] workingFolderCurrent true [markup.asciidocExt.attributes] my-base-url https://example.com/ my-attribute-name my valueAsciiDoc 语法高亮按以下步骤启用语法高亮步骤 1在项目配置中设置source-highlighter属性例如[markup.asciidocExt.attributes] source-highlighter rouge步骤 2生成高亮器 CSS例如rougify style monokai.sublime assets/css/highlight.css步骤 3在base模板中引入该 CSS 文件head {{ with resources.Get css/highlight.css }} link relstylesheet href{{ .RelPermalink }} integrity{{ .Data.Integrity }} crossoriginanonymous {{ end }} /head步骤 4在文档中书写待高亮代码[#hello,go] ---- package main import fmt func main() { fmt.Println(Hello, World!) } ----故障排查运行hugo build --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 outdirD:\prototypes\hugo_asciidoc_ddd\build -] ...从日志可见noHeaderOrFooter会映射为命令行参数--no-header-footerextensions中的每一项映射为-r参数backend映射为-b参数。需要留意的是源码 markup/asciidocext/asciidocext_config/config.go 将outdir列为禁用属性DisallowedAttributes用户配置中不可覆盖它因为 Hugo 需要控制输出目录。reStructuredText 渲染器使用rst时Hugo 调用外部的 Docutils 可执行文件rst2html系列命令完成渲染。默认配置见 markup/rst/rst_config/config.go[markup.rst] syntaxHighlight long设置syntaxHighlight: string使用 Pygments 解析代码时的 token 名称集合取值为long、short或none默认long。源码 markup/rst/rst_config/config.go 的Init会对非法的取值直接报错invalid value for syntaxHighlight: ...。reStructuredText 语法高亮步骤 1将syntaxHighlight设为short[markup.rst] syntaxHighlight short步骤 2生成高亮器 CSS例如pygmentize -S monokai -f html assets/css/highlight.css步骤 3在base模板中引入该 CSS 文件head {{ with resources.Get css/highlight.css }} link relstylesheet href{{ .RelPermalink }} integrity{{ .Data.Integrity }} crossoriginanonymous {{ end }} /head步骤 4在文档中书写待高亮代码.. code-block:: go package main import fmt func main() { fmt.Println(Hello, World!) }代码高亮Highlight以下设置适用于 Markdown 围栏代码块、内嵌的highlightshortcode、transform.Highlight与transform.HighlightCodeBlock函数。默认配置见 markup/highlight/config.go[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参数为空或对应语言没有词法分析器lexer时是否自动检测语言若检测失败则回退为纯文本。默认false。[!NOTE] 语法高亮器内置约 300 种语言的 lexer但其中只有 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置为falsetable启用基于表格的行号同时将lineNumbersInTable置为true。lineNumbersInTable: bool是否将高亮代码渲染为两单元格的 HTML 表格左单元格为行号右单元格为代码。lineNos为false时无效。默认true。noClasses: bool是否使用内联 CSS 样式而非外部 CSS 文件默认true。若需使用外部 CSS 文件设为false并用以下命令生成hugo gen chromastyles --stylegithub assets/css/highlight.css部分样式提供独立的亮色 / 暗色配色。使用--mode标志为指定模式生成样式表用--modeSelector标志将每个选择器限定在顶层模式类下如.dark .chromahugo gen chromastyles --stylemonokai --modelight assets/css/highlight.css hugo gen chromastyles --stylemonokai --modedark --modeSelector assets/css/highlight-dark.css通过增删根元素上的dark类即可切换暗色模式。省略--mode时Hugo 使用该样式的默认模式生成样式表。此外也可在模板内用css.ChromaStyles函数生成样式表。style: string应用于高亮代码的 CSS 样式名不区分大小写默认monokai。可选样式参见 syntax highlighting styles。tabWidth: int每个 tab 字符替换为的空格数noClasses为false时无效。默认4。wrapperClass: string新增于 0.140.2高亮代码最外层元素的 class 名默认highlight。从实现看markup/highlight/config.go 的toHTMLOptions会将上述配置转换为 Chroma 的 HTML 渲染选项其中lineNos的字符串形式inline/table会映射为对应的表格开关hl_Lines会被解析为行区间数组[2][4]int传给 Chroma 渲染强调行。此外该包还保留了 Pygments 时代的旧配置兼容pygmentsStyle、pygmentsUseClasses、pygmentsCodeFences、pygmentsCodefencesGuessSyntax、pygmentsOptions等遗留键仍会被ApplyLegacyConfig自动迁移markup/highlight/config.go。目录Table of contents目录配置同时适用于 Goldmark 与 Asciidoctor默认配置如下对应源码 markup/tableofcontents/tableofcontents.go[markup.tableOfContents] endLevel 3 ordered false startLevel 2startLevel: int级别小于该值的标题将被排除在目录外。例如要排除h1将其设为2。默认2。endLevel: int级别大于该值的标题将被排除在目录外。例如要排除h4、h5、h6将其设为3。默认3。源码 markup/tableofcontents/tableofcontents.go 还支持-1表示包含所有层级。ordered: bool是否生成有序列表ol而非无序列表ul默认false。在 markup/tableofcontents/tableofcontents.go 的tocBuilder中可以看到目录的完整渲染逻辑writeNav输出nav idTableOfContents容器writeHeadings依据startLevel/stopLevel决定哪些层级进入列表ordered决定输出ol还是ul最终生成的Fragments数据结构同时供模板中的TableOfContents方法使用。小结markup配置区块覆盖了 Hugo 内容渲染的完整链路defaultMarkdownHandler决定使用哪个渲染器markup.goldmark控制内置 Goldmark 引擎的扩展、解析器与渲染行为markup.asciidocExt、markup.rst分别对接 Asciidoctor 与 Docutils 两个外部渲染器markup.highlight统一管理围栏代码块与 shortcode 的 Chroma 高亮markup.tableOfContents则约束目录生成范围。绝大多数配置在 markup/markup_config/config.go 中被一次解码并注入转换器注册表markup/markup.go其中goldmark.parser.attribute、typographer、footnote等历史结构变更均有自动迁移逻辑升级 Hugo 时无需手工改写旧配置。以本文的配置示例为起点你可以为多语言站点、数学文档或 AsciiDoc 工作流构建贴合自身需求的渲染管线。【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考