引用

三个 shortcode 各做一件事：include 把另一个文件的内容放进当前页面，param 打印一个页面或站点参数，comment 丢弃一段内容。适用于跨页复用的片段与散落在多页的常量：同一段安装步骤出现在三页时用 include，版本号出现在几十页时用 param，改一处即可。只在一页出现的内容写在那一页。

最简例子

include 只有一个必填参数 file：

{{< include file="parts/install-oink.zh.md" >}}

被引的文件是一段普通 Markdown，放在 assets/ 下：

把 OINK 安装到一个已有的 Hugo 站点，三条命令：

```sh
hugo mod init github.com/you/your-site
hugo mod get github.com/pgsty/oink
hugo server
```

> [!NOTE]
> `hugo mod get` 需要本机安装 Go；用离线归档或 submodule 时不需要。

当前发布版本是 {{< param version >}}。

渲染结果与写在本页里相同：代码块有复制按钮，提示块是提示块。

把 OINK 安装到一个已有的 Hugo 站点，三条命令：

hugo mod init github.com/you/your-site
hugo mod get github.com/pgsty/oink
hugo server

当前发布版本是 v0.6.0。

被引的文件不是一篇独立页面：它不出现在侧栏、不参与翻译配对、没有自己的 URL。

文件位置

file 按下面的顺序解析，第一个命中的胜出：

三处都找不到时构建失败，不输出占位内容。路径里含 .. 也让构建失败：引用只能在 content/ 与 assets/ 中取文件。

引 Markdown 片段时写文件在磁盘上的真名。有一个陷阱只属于第 1 步：Hugo 把带语言后缀的页面资源（如 notice.zh.md）按去掉后缀的名字挂在页面上，向页面包索取 notice.md 拿到的是已渲染的 HTML 而不是源码，Markdown 输出里会出现 <div class="td-code">。assets/ 与 content/ 下写什么名字就取什么文件，没有这层转换。非 Markdown 文件（.yaml、.sh、.txt）也没有这个区别。

本页两种语言各引一份自己的片段：中文引 assets/parts/install-oink.zh.md，英文引 assets/parts/install-oink.md。片段放在 assets/ 下而不是页面包里，两种语言就都按写下的名字取到源码。

引入代码文件

加 code=true 让文件按代码块渲染，lang= 指定高亮语言。引用仓库里的真实配置文件，文档与实际文件不会不一致。

{{< include file="parts/module.zh.yml" code=true lang="yaml" >}}

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

代码块与围栏走同一条渲染管线：高亮、行号、复制按钮都有。围栏属性（title=、collapse、hl_lines=）传不进来，需要它们时把文件内容写成普通代码块。

片段内容

片段是页面级 Markdown，在当前页面的上下文里渲染：提示块、表格、列表、图片、步骤与 shortcode 都可以用。上面那段片段结尾的「当前发布版本是 v0.6.0」，是片段里的 {{< param version >}} 在本页展开的结果。

一个片段被两页引用时，两页各自渲染一遍，各自生成标题锚点与代码块 ID，互不冲突。

插入站点参数

param 打印一个参数：先查本页 front matter，查不到再查站点配置（Hugo 的 .Param 规则）。

本站发布版本 {{< param version >}}，版权起始年 {{< param copyright.from_year >}}，
本页 front matter 里写了 `pigsty_pg_major: 18`，这里取到 {{< param pigsty_pg_major >}}。

本站发布版本 v0.6.0，版权起始年 2026， 本页 front matter 里写了 pigsty_pg_major: 18，这里取到 18。

嵌套键用 . 连接，copyright.from_year 取的是 params.copyright.from_year。参数不存在、或者值是 map 与列表而不是标量时构建失败，不会留下空白。

在命令、表格与链接里插参数

param 的输出是转义后的纯文本，可以放进代码围栏、表格单元格与链接地址。安装命令里的版本号适合这么写：

```sh
hugo mod get github.com/pgsty/oink@{{< param tdVersion.latest >}}
```

| 项目 | 值 |
| --- | --- |
| 当前版本 | {{< param version >}} |
| Hugo 下限 | {{< param hugoMinVersion >}} |

[发布说明](https://github.com/pgsty/oink/releases/tag/{{< param tdVersion.latest >}})

hugo mod get github.com/pgsty/[email protected]

发布说明

站点参数在哪里定义、有哪些可用，见配置总览；页面参数见页面参数。

构建期删除的注释

comment 的内容在 HTML、打印、Markdown、RSS 四种输出里都不出现。HTML 注释不同：它留在页面源码里，也会进入 llms.txt。

PostgreSQL 18 起 `pg_stat_io` 拆分了 WAL 统计。

{{< comment >}}
待办：v0.5 发布后把上面的版本号换成 19，并补一张 pg_stat_io 的截图。
这段文字不会出现在任何输出里，包括 llms.txt。
{{< /comment >}}

升级前先在测试库上验证监控面板。

PostgreSQL 18 起 pg_stat_io 拆分了 WAL 统计。

升级前先在测试库上验证监控面板。

上面两段之间有一段注释，查看页面源码也找不到它。

输出形态

Markdown 输出里片段是源码而不是 HTML，片段里的 shortcode 保持 {{< param version >}} 的原样。这与「Markdown 输出保留源码」一致，不是漏渲染。三个 shortcode 都不加载脚本。

参数参考

include（只接受具名参数）：

其它任何参数名都会构建失败，报错里带文件名与行号。

param（一个位置参数）：

comment 没有参数，成对使用，{{< comment >}} 与 {{< /comment >}} 之间的内容整段丢弃。

限制与常见问题

• include 不是模板：不能向片段传变量、不能条件引入、不能给引入的代码块加围栏属性（title=、collapse）。按平台分版本时写两个片段配标签页。
• 片段的语言要自己维护：include 不做语言回退。中文页引中文片段，英文页引英文片段，两份文件并列存放（install-oink.zh.md 与 install-oink.md）。
• param 只打印标量：结构化数据（版本矩阵、下载列表）用 data/ 目录里的数据配对应组件渲染。
• comment 不是「暂时不发布」：内容每次构建都被丢弃，临时下线整页用 draft: true。
• 不把 include 当目录页：一页引入十个片段时，读者需要的是十条链接。

相关

• 代码块 — 围栏的全部属性，include code=true 用的是同一套渲染
• 标签页 — 按平台 / 语言分版本的片段
• 配置总览 — param 能取到的站点参数
• 页面参数 — 页面级参数，优先于站点配置