内容格式

内容格式（content format）指内容源文件所使用的标记语言。Hugo 首先依据前置元数据（front matter）里的 markup 标识符选择内容渲染器，只有未提供该字段时才回退到文件扩展名。格式是逐文件判定的，因此同一个站点里可以混用多种格式：

content/
└── posts/
    ├── post-1.md
    ├── post-2.adoc
    ├── post-3.org
    ├── post-4.pandoc
    ├── post-5.rst
    └── post-6.html

无论使用哪种格式，内容文件都必须带有前置元数据，最好同时写出 title 与 date，详见前置元数据。

支持的格式

Markdown

Markdown 是 Hugo 的默认内容格式，由内置的 Goldmark 渲染器直接渲染为 HTML。Goldmark 速度快，并遵循 CommonMark 与 GitHub Flavored Markdown 规范，可以在项目配置的 [markup.goldmark] 区段中调整。

Hugo 在 Markdown 之上提供了这些专有能力：

• 属性（attributes）：把 class、id 等 HTML 属性施加到图片以及引用块、围栏代码块、标题、水平线、列表、段落、表格等块级元素上，见内容格式属性。
• 扩展（extensions）：启用内置 Markdown 扩展，用来书写表格、定义列表、脚注、任务列表、插入文本、标记文本、下标、上标等。
• 数学公式（mathematics）：用 LaTeX 标记书写数学公式与表达式，见数学公式。
• 渲染钩子（render hooks）：在渲染围栏代码块、标题、图片与链接时覆盖 Markdown 到 HTML 的转换逻辑，例如把每个独立图片渲染为 HTML 的 figure 元素，见渲染钩子。

HTML

把内容写在 HTML 标记中，前面照常加前置元数据。内容通常相当于 HTML 文档 body 或 main 元素里会放置的部分，由 Hugo 直接输出，不再做 Markdown 转换。

注意：HTML 内容格式默认被拒绝，需要配置 security.allowContent 才可使用。

Emacs Org Mode

把内容写在 Emacs Org Mode 格式中，前面加前置元数据。前置元数据也可以用 Org Mode 关键字书写，详见前置元数据中的 Org Mode 写法。

注意：Emacs Org Mode 内容格式默认被拒绝，需要配置 security.allowContent 才可使用。

AsciiDoc

把内容写在 AsciiDoc 格式中，前面加前置元数据。Hugo 调用 asciidoctor 可执行文件把 AsciiDoc 渲染为 HTML，因此必须在本机安装 asciidoctor 及其依赖（Ruby）。

注意：Hugo 的默认安全策略不允许执行 asciidoctor 二进制文件，必须把它加入项目配置中的 security.exec.allow 列表。

可以在项目配置中配置 AsciiDoc 渲染器。默认配置下，Hugo 调用 asciidoctor 时传入的命令行标志为：

--no-header-footer

传入的标志取决于配置，构建时可以查看实际使用的标志：

hugo build --logLevel info

Pandoc

把内容写在 Pandoc 格式中，前面加前置元数据。Hugo 调用 pandoc 可执行文件把 Pandoc 渲染为 HTML，因此必须在本机安装 pandoc。

注意：Hugo 的默认安全策略不允许执行 pandoc 二进制文件，必须把它加入项目配置中的 security.exec.allow 列表。

Hugo 调用 pandoc 时传入的标志取决于本机安装的 Pandoc 版本。如果安装的版本支持 Pandoc 3.11 引入的 --math-method 标志：

--citeproc --math-method=mathjax

否则：

--citeproc --mathjax

（自 Hugo 0.164.0 起提供。）--citeproc 标志启用 Pandoc 的引文处理。使用 Pandoc 的文献与引文功能时，文献文件路径、引文样式、行内引用定义等设置通过内容文件里的元数据块控制，例如：

---
title: home
---

This is a paragraph followed by a metadata block.

---
bibliography: foo.bib
citation-style: ieee.csl
link-citations: true
---

This is a citation: @einstein1905physics

注意：文献文件与引文样式文件必须位于本地文件系统上，不能从 Hugo 模块导入；路径可以相对于项目根目录，也可以是绝对路径。

reStructuredText

把内容写在 reStructuredText 格式中，前面加前置元数据。Hugo 通过 Docutils 的 rst2html 把 reStructuredText 渲染为 HTML，因此必须安装 Docutils 及其依赖（Python）。

注意：Hugo 的默认安全策略不允许执行 rst2html 二进制文件，必须把它加入项目配置中的 security.exec.allow 列表。

Hugo 调用 rst2html 时传入的命令行标志为：

--leave-comments --initial-header-level=2

渲染器分类与配置

把内容转换为 HTML 时，Hugo 使用：

• 原生渲染器：Markdown、HTML、Emacs Org Mode。
• 外部渲染器：AsciiDoc、Pandoc、reStructuredText。

原生渲染器比外部渲染器更快。外部渲染器相关的选项位于项目配置的 [markup] 区段中并按格式分节，例如 AsciiDoc 的选项在 [markup.asciidocExt]；这些格式能否使用，取决于构建机器上是否装好了对应的外部程序，程序缺失时构建会报错。模板与内容格式无关：无论源文件用什么格式，渲染后的页面都由同一套模板输出。