内容管理 on Hugo 中文文档

内容格式

Thu, 01 Oct 2026 00:00:00 +0800

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

前置元数据

Thu, 01 Oct 2026 00:00:00 +0800

前置元数据（front matter）是每个内容文件顶部的一段元数据，用来描述内容、补充内容、建立与其他内容的关系、控制站点的发布结构，并决定 Hugo 选用哪个模板。它用 JSON、TOML 或 YAML 之一序列化，Hugo 通过分隔前置元数据与正文的定界符来判断用的是哪一种。

页面包

Thu, 01 Oct 2026 00:00:00 +0800

页面包（page bundle）是一个目录，把内容与相关资源封装在一起。例如下面这个站点有一个 about 页面和一个 privacy 页面：

content/
├── about/
│   ├── index.md
│   └── welcome.jpg
└── privacy.md

about 页面就是一个页面包：它把资源与内容打包在一起，从而在逻辑上建立关联。页面包内的资源称为页面资源，可以用 Page 对象的 .Resources 方法访问。

页面资源

Thu, 01 Oct 2026 00:00:00 +0800

页面资源（page resource）是只允许从页面包访问的文件，也就是根目录下带有 index.md 或 _index.md 的那些目录中的文件。页面资源只对与它打包在一起的那个页面可用，叶子包与分支包都是如此。

内容组织

Thu, 01 Oct 2026 00:00:00 +0800

内容目录即站点结构

Hugo 假定用于组织源内容的结构，同样用于组织渲染后的站点。内容在 content/ 目录中的位置构成一棵逻辑树：一级子目录即顶层 section，目录名既是 section 名，也是 URL 的一段。内容属于哪个 section 由它在目录树中的位置决定，不能在前置元数据中指定或覆盖。

内容区块

Thu, 01 Oct 2026 00:00:00 +0800

概述

section（内容区块）是组织内容的一种方式。Hugo 假定用于组织源内容的结构同样用于组织渲染后的站点，content/ 目录下的一级目录就是顶层 section，目录名既是 section 名，也直接成为 URL 的一段。Hugo 依据内容所在的位置推断它属于哪个 section，不能在前置元数据（front matter）中指定或覆盖。

原型

Thu, 01 Oct 2026 00:00:00 +0800

原型是什么

一份内容文件由前置元数据（front matter）与正文标记组成，正文通常是 Markdown，也可以是 Hugo 支持的其他内容格式；前置元数据可以是 TOML、YAML 或 JSON。原型（archetype）是创建新内容时使用的模板，hugo new content 命令会以某个原型为依据，在 content 目录下生成新文件。Hugo 内置的默认原型相当于：

摘要

Thu, 01 Oct 2026 00:00:00 +0800

菜单

Thu, 01 Oct 2026 00:00:00 +0800

菜单系统的三个环节

菜单（menu）由一组菜单项（menu entry）组成，每一项最终渲染为一个链接。为站点建立菜单需要三步：定义菜单项、为每种语言本地化菜单项、在模板中渲染。站点可以有多个菜单，既可以平铺也可以嵌套，例如页头放一个主菜单，页脚再放一个独立菜单。

分类法

Thu, 01 Oct 2026 00:00:00 +0800

什么是分类法

Hugo 支持自定义的内容分组机制，称为分类法（taxonomy）。分类法描述内容之间的逻辑关系，由三个层次构成：

分类法（taxonomy）: 一种可用于归类内容的分类维度。
术语（term）: 分类法中的一个键（取值）。
值（value）: 被指派给某个术语的一篇内容。

以影视站点为例，可以定义演员、导演、制片公司、类型、年份、奖项等多个分类法。在每部影片的 front matter 中为这些分类法写下术语之后，Hugo 会自动为每个演员、导演、制片公司、类型、年份与奖项生成页面，并在页面上列出所有符合该条件的影片。

多语言

Thu, 01 Oct 2026 00:00:00 +0800

配置

多语言站点的语言清单与默认语言都在项目配置中声明。以下是基础设置：

defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
disableDefaultLanguageRedirect = false
disableLanguages = []

defaultContentLanguage 是项目的默认语言，写法遵循 RFC 5646；定义了一种或多种语言后，该值必须与某个已定义的语言键匹配。

URL 管理

Thu, 01 Oct 2026 00:00:00 +0800

概述

默认情况下，Hugo 渲染页面时生成的 URL 与文件在 content 目录中的路径一致。例如：

content/posts/post-1.md -> https://example.org/posts/post-1/

通过 front matter 取值与项目配置，可以改变 URL 的结构与外观。

Markdown 属性

Thu, 01 Oct 2026 00:00:00 +0800

概述

Hugo 支持在图片，以及引用块（blockquote）、围栏代码块（fenced code block）、标题、水平分隔线、列表、段落、表格等块级元素上使用 Markdown 属性（Markdown attributes）。

语法高亮

Thu, 01 Oct 2026 00:00:00 +0800

三种高亮方式

Hugo 用 Chroma 完成语法高亮（syntax highlighting），提供三条途径：在模板中调用 transform.Highlight 函数、在任何内容格式中使用 highlight 短代码（shortcode），以及在 Markdown 内容格式中使用围栏代码块（code fence）。日常写作以第三种为主。

图像处理

Thu, 01 Oct 2026 00:00:00 +0800

图像处理概览

Hugo 可以在构建过程中转换与分析图像。任何图片格式都能作为资源管理，但只有可处理的图像（processable image）才能用下文的方法转换；处理结果会写入缓存，以保证后续构建依旧很快。判断一张图片能否处理，用 reflect.IsImageResourceProcessable 函数。

图表

Thu, 01 Oct 2026 00:00:00 +0800

图表方案概览

在内容中插入图表大致有两条路线：一是构建期渲染（render at build time），由 Hugo 把图表描述直接转换成静态标记；二是浏览器端渲染（render in browser），页面先输出图表源码，再由加载的 JavaScript 库把它画出来。Hugo 对前者中的 GoAT 提供了内置支持，对 Mermaid 之类则要由站点自己编写渲染钩子（render hook）来接管。两条路线的依赖、产物与适用场景都不相同。

数学公式

Thu, 01 Oct 2026 00:00:00 +0800

概览

用 LaTeX 标记书写的数学公式在学术与科技内容中很常见，浏览器通常借助 MathJax 或 KaTeX 这类开源 JavaScript 排版引擎把它渲染出来。例如下面这段 LaTeX 标记：

\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]

公式可以与正文同行显示（行内公式），也可以独占一块（块级公式，即 display 模式）。究竟按哪种方式呈现，取决于包裹标记的定界符（delimiter）。定界符成对出现，一对由开定界符与闭定界符组成，两者可以相同，也可以不同。

Thu, 01 Oct 2026 00:00:00 +0800

评论功能与 Hugo

Hugo 内置了对 Disqus 的支持。Disqus 是一项第三方服务，通过 JavaScript 为网站提供评论与社区功能。评论数据的存储、审核与展示都在服务端完成，Hugo 只负责在页面上输出挂载代码——静态站点本身没有数据库，也没有可以写入评论的服务端接口，所以「在 Hugo 里加评论」实际上就是把第三方提供的嵌入片段放进模板。

构建选项

Thu, 01 Oct 2026 00:00:00 +0800

页面级构建选项

构建选项存放在前置元数据（front matter）中一个名为 build 的保留对象里（早期版本写作 _build），它的默认值如下：

+++
title = "示例页面"
[build]
list = 'always'
publishResources = true
render = 'always'
+++

list 决定页面在何时进入页面集合：

内容适配器

Thu, 01 Oct 2026 00:00:00 +0800

概述

内容适配器（content adapter）是一种在构建站点时动态创建页面的模板。例如，可以用它根据远程数据源生成页面，数据格式可以是 JSON、TOML、YAML 或 XML。

数据源

Thu, 01 Oct 2026 00:00:00 +0800

概述

Hugo 可以访问并解析本地与远程数据源，支持的格式包括 CSV、JSON、TOML、YAML 与 XML。用这些数据可以增强既有内容，也可以创建新内容。

内容管理 on Hugo 中文文档

内容格式

前置元数据

页面包

页面资源

内容组织

内容目录即站点结构

内容区块

概述

原型

原型是什么

摘要

相关内容

相关内容如何工作

菜单

菜单系统的三个环节

分类法

什么是分类法

多语言

配置

URL 管理

概述

Markdown 属性

概述

语法高亮

三种高亮方式

图像处理

图像处理概览

图表

图表方案概览

数学公式

概览

评论

评论功能与 Hugo

构建选项

页面级构建选项

内容适配器

概述

数据源

概述