Hugo 内容格式

介绍

你可以在整个站点中混合使用内容格式。例如：

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

无论内容格式如何，所有内容都必须有 front matter，最好包括 title 和 date。

Hugo 根据 front matter 中的 markup 标识符选择内容渲染器，回退到文件扩展名。参见下面的 [分类] 表，了解 markup 标识符和已识别文件扩展名的列表。

格式

Markdown

使用 Markdown 创建内容，前面加上 front matter。

Markdown 是 Hugo 的默认内容格式。Hugo 使用 Goldmark 原生将 Markdown 渲染为 HTML。Goldmark 速度快并且符合 CommonMark 和 GitHub Flavored Markdown 规范。你可以在 站点配置 中配置 Goldmark。

Hugo 提供自定义 Markdown 功能，包括：

Attributes

将 HTML 属性（如 class 和 id）应用于 Markdown 图像和块元素，包括引用块、围栏代码块、标题、水平线、列表、段落和表格。

Extensions

利用嵌入式 Markdown 扩展创建表格、定义列表、脚注、任务列表、插入文本、标记文本、下标、上标等。

Mathematics

使用 LaTeX markup 在 Markdown 中包含数学方程和表达式。

Render hooks

在渲染围栏代码块、标题、图像和链接时覆盖 Markdown 到 HTML 的转换。例如，将每个独立图像渲染为 HTML figure 元素。

HTML

使用 HTML 创建内容，前面加上 front matter。内容通常是你放在 HTML 文档的 body 或 main 元素中的内容。

Emacs Org Mode

使用 Emacs Org Mode 格式创建内容，前面加上 front matter。你可以使用 Org Mode 关键字作为 front matter。参见 [详情]。

AsciiDoc

使用 AsciiDoc 格式创建内容，前面加上 front matter。Hugo 使用 Asciidoctor 可执行文件将 AsciiDoc 内容渲染为 HTML。你必须安装 Asciidoctor 及其依赖项（Ruby）才能渲染 AsciiDoc 内容格式。

你可以在 站点配置 中配置 AsciiDoc 渲染器。

在默认配置中，Hugo 在调用 Asciidoctor 可执行文件时传递以下 CLI 标志：

--no-header-footer

传递给 Asciidoctor 可执行文件的 CLI 标志取决于配置。你可以在构建站点时检查这些标志：

hugo --logLevel info

Pandoc

使用 Pandoc 格式 ¹ 创建内容，前面加上 front matter。Hugo 使用 Pandoc 可执行文件将 Pandoc 内容渲染为 HTML。你必须安装 Pandoc 才能渲染 Pandoc 内容格式。

Hugo 在调用 Pandoc 可执行文件时传递以下 CLI 标志：

--mathjax

reStructuredText

使用 reStructuredText 格式创建内容，前面加上 front matter。Hugo 使用 Docutils（特别是 rst2html）将 reStructuredText 内容渲染为 HTML。你必须安装 Docutils 及其依赖项（Python）才能渲染 reStructuredText 内容格式。

Hugo 在调用 rst2html 可执行文件时传递以下 CLI 标志：

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

分类

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

• Markdown、HTML 和 Emacs Org mode 的原生渲染器
• AsciiDoc、Pandoc 和 reStructuredText 的外部渲染器

原生渲染器比外部渲染器更快。