组件总览

• 1: 提示块
• 2: 图片
• 3: 代码块
• 4: 标签页
• 5: 表格
• 6: 参数表
• 7: 步骤
• 8: 卡片
• 9: 文件树
• 10: 公式
• 11: Mermaid
• 12: PlantUML
• 13: 思维导图
• 14: Draw.io
• 15: ECharts
• 16: Infographic
• 17: 画廊
• 18: 徽章
• 19: 按键
• 20: 引用
• 21: Asciinema

markup:
  goldmark:
    renderer:
      unsafe: true # 内容里的 HTML 不被剥掉
    parser:
      attribute:
        block: true # 启用 {…} 属性行
      wrapStandAloneImageWithinParagraph: false # 独立图片不再包进 <p>

1 - 提示块

提示块（Callout）是 GitHub / Obsidian 风格的块引用：> [!TYPE] 起头，正文跟在后面。用于把提示、警告、前提条件从正文中分离出来；正文一句话能说清的内容不必使用提示块。

最简例子

> [!NOTE]
> Hugo Module 需要本机安装 Go；只用离线归档时不需要。

不写标题时使用本地化的类型名（中文站显示「注意」，英文站显示 “Note”）。源码在 GitHub 上按 GitHub 的提示块渲染，在普通 Markdown 阅读器中显示为块引用，内容都不会丢失。

十种类型

前五种与 GitHub 一致，后五种是 OINK 追加的语义类型。每种类型有默认图标与强调色。

> [!TIP]
> 用 `hugo server -D` 可以预览草稿。

> [!IMPORTANT]
> 主题下限是 Hugo Extended 0.160.1，低于它构建直接失败。

> [!WARNING]
> `hugo --cleanDestinationDir` 会清空 `public/`。

> [!CAUTION]
> 删除 `resources/_gen` 后第一次构建会慢很多。

> [!SUCCESS]
> 构建通过、零告警——可以推上线了。

> [!DANGER]
> 不要把 `go.work` 提交进仓库。

> [!QUESTION]
> 站点要不要开评论？看[启用评论](/zh/docs/admin/comments/)。

> [!EXAMPLE]
> `pgsty.com` 就是一个只用了提示块与表格的纯文档站。

> [!QUOTE]
> Documentation is a love letter that you write to your future self.

类型名不区分大小写。

自定义标题

标记同一行的后续文字是标题，支持行内 Markdown（代码、粗体、链接）。

> [!WARNING] 会改写 `public/`
> 生产构建前先确认 `baseURL` 指向正式域名，否则所有绝对链接都会指错。

正文内容

正文是页面级 Markdown：列表、代码围栏、表格、图片、嵌套的提示块。每一行都以 > 开头，围栏也不例外。

> [!TIP] 三条命令启动预览
>
> 1. 克隆：`git clone https://github.com/pgsty/oink.pgsty.com my-docs`
> 2. 进入目录并预览：
>    ```bash
>    cd my-docs && hugo server
>    ```
> 3. 打开 <http://localhost:1313/>
>
> | 端口 | 用途 |
> | --- | --- |
> | 1313 | Hugo 开发服务器 |

折叠

类型后加 - 默认收起，加 + 默认展开；两者都渲染为原生 <details>，不加载 JavaScript。适用于完整输出、备选方案、背景说明这类不必默认展示的内容。

> [!NOTE]- 为什么需要 Go？
> Hugo 通过 Go 的模块系统下载主题（`hugo mod get`）。用 submodule 或离线归档时可以不装 Go。

> [!TIP]+ 默认展开，但读者可以收起
> 收起状态不会被记住，刷新后回到默认。

中性折叠块 DETAILS

[!DETAILS] 是没有语义颜色的折叠块：不加符号默认收起，[!DETAILS]+ 默认展开。用于冗长输出、完整配置文件等需要折叠的内容。

> [!DETAILS] 完整的 `hugo version` 输出
> ```text
> hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z VendorInfo=Homebrew
> ```

hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z VendorInfo=Homebrew

自定义图标

块引用结束后的下一行写属性 {icon="fa-solid fa-xxx"}（一对 Font Awesome class），替换该类型的默认图标。属性行紧接块引用，中间不能有空行。

> [!TIP] PostgreSQL 18 已支持
> 从 Pigsty v4 起默认安装 PostgreSQL 18。
{icon="fa-solid fa-database"}

嵌套

提示块可以嵌套（每层多一个 >），也可以放在列表项或步骤中。建议最多嵌套一层。

> [!WARNING] 升级前先备份
> 升级主题版本可能改变渲染结果。
>
> > [!TIP]- 怎么备份
> > `git tag pre-upgrade` 就够了——回滚只是 `git checkout pre-upgrade`。

未知类型与易错写法

未知的类型名不会导致构建失败，也不会丢失内容：该块渲染为普通块引用，[!TYPE] 标记原样可见。

> [!NOTICE] 这不是合法类型
> 标记会保留在页面上提醒你。

[!NOTICE] 这不是合法类型

标记会保留在页面上提醒你。

其它常见问题：

• 正文与标题合并：经过 Prettier 等格式化工具的文件，在标题行下保留一个空的 > 行，否则工具会把标题并入正文。
• 属性行被格式化工具移动：把 {icon=…} 这类标记行放在 <!-- prettier-ignore-start --> / <!-- prettier-ignore-end --> 之间。
• style、onclick 等属性导致构建失败：属性行只接受 icon 与 class（见下表）。

输出形态

提示块不加载脚本。

参数参考

标记行 > [!TYPE]± 标题：

属性行 {…}（块引用之后紧接的一行）：

style、on* 与其它任何键都会让构建失败。

限制与常见问题

• 不能自定义颜色：颜色由类型决定，需要新语义时选最接近的类型并自定义标题。
• 折叠状态不持久化。
• 提示块可以放在 {.steps} 列表项与 {{%/* steps */%}} 步骤中（见步骤），块引用的每一行都以 > 开头，缩进与列表项对齐。

相关

• 步骤 — 步骤中放置提示块
• 标签页 — 同一提示按平台分开呈现
• 编写页面 — 提示块与正文的取舍

2 - 图片

图片只有一种写法：Markdown 的 ![替代文字](来源 "标题")。独立成段的图片可以在下一行跟一行 {…} 属性，成为带图注的 figure、缩放候选、编号图或经 Hugo 处理的派生图。主题没有图片 shortcode。

最简例子

![OINK 文档外壳：侧栏、正文与目录三栏](oink-shell.webp)

这张图与本页放在同一目录（页面包）中，主题读取它的固有尺寸并写入 width/height，页面加载时不发生跳版；所有图片懒加载。替代文字供屏幕阅读器与搜索引擎使用，应当始终填写；空 alt 表示装饰性图片，缩放会跳过它。

图片来源

来源按以下顺序解析，写法相同：

相对路径先按页面资源、再按全局资源查找，都找不到时按静态路径原样输出；主题不检查静态路径与远程 URL 是否存在。只有要求处理（command=）的图找不到资源时才构建失败。

行内与块级

位于文字中间的是行内图片，渲染为一个 <img>，不能带属性；独立成段的是块级图片，可以带属性行。

这一枚小图 ![文档外壳缩略图](oink-mini.webp) 夹在句子里，是行内图片。

![文档外壳缩略图](oink-mini.webp)
{width="100" height="64"}

这一枚小图 夹在句子里，是行内图片。

行内图片按自身尺寸显示（这里是 50×32）。没有固有尺寸的 SVG 行内插入时会被拉伸到容器宽度，SVG 应作为块级图片使用并给出 width/height。

图注

属性行加 caption="…"，图片渲染为 <figure> + <figcaption>。图注是纯文本，不解析 Markdown。

![发布卡片：版本号、发布日期与资产按钮](release-note.webp)
{caption="发布卡片由 data/download 与页面的 release 记录生成"}

Markdown 里的 "标题" 保持原义（悬停提示），不会成为图注。

尺寸

width/height 是正整数，覆盖资源自身的尺寸：为静态或远程图片提供占位框以避免跳版，或把大图缩小显示（浏览器缩放，不改文件）。

![OINK 首页插画（浅色）](/images/hero-light.webp)
{width="450" height="300" caption="static/images/ 里的 900×600 插画按一半显示"}

处理型图片

页面资源与全局资源可以在构建期由 Hugo 处理：command 与 options 必须同时给出，命令是 Fit Resize Fill Crop 之一，选项是 Hugo 的图片处理字符串。渲染出的 src 是派生图；启用缩放时对话框打开原图。

![文档外壳缩略图](oink-shell.webp)
{command="Fit" options="300x150" caption="Fit 300x150：按比例装进 300×150 的框"}

![文档外壳左半边](oink-shell.webp)
{command="Fill" options="300x150 Left" caption="Fill 300x150 Left：填满框，从左侧裁"}

静态路径、远程 URL 与 SVG 不能处理，对它们写 command 会构建失败。选项语法（锚点、质量、格式转换，如 300x150 webp q80）见 Hugo 图片处理。

链接图片

两种写法，用途不同：

• 没有图注、图片本身是链接：用 Markdown 的链接包图 [![alt](src)](href)。
• 有图注的 figure 整体可点：属性行加 link="…"（必须同时有 caption 或 num）。

[![点击进入亮点特性页](oink-shell.webp)](/zh/docs/about/features/)

![发布卡片](release-note.webp)
{caption="点击图片查看发布与下载页的说明" link="/zh/docs/write/releases/"}

带链接的图不参与缩放。没有图注只写 link= 会构建失败，报错中提示改用 [![…](…)](…)。

编号图

编号图用于书籍与长篇手册：属性行加 num，可选 #id。编号是作者书写的字符串（2-1、3.4），主题不自动计数；图注前加本地化的「图 2-1」前缀，#id 缺省为 fig-<num>。正文用普通链接 [图 2-1](#fig-2-1) 或 xref shortcode 引用；全书图目录见书籍出版。

![发布卡片](release-note.webp)
{#fig-release num="2-1" caption="发布卡片：版本、日期与资产"}

见[图 2-1](#fig-release)。

见图 2-1。

编号图可以同时是处理型图片（num + command），也可以带 link。

缩放

图片缩放默认关闭。站点开启后，块级图片、figure、画廊中带 alt 的图成为可点击的按钮，在原生 <dialog> 中查看大图（Esc 关闭，焦点回到原处）。本页在 front matter 中开启了它，上面的图都可以点击。

params:
  ui:
    image_zoom: true

image_zoom: false

不缩放的图：行内图、alt 为空的装饰图、带链接的图、data-no-zoom 标记的图。运行时只在页面确有候选图时加载；打印 / Markdown / RSS 中没有对话框。

![](oink-shell.webp)
{width="150" height="75"}

深浅色图片

主题没有按深浅色切换图片的参数。需要两张图时，各写一个 class，在站点 CSS 中按 [data-bs-theme="dark"] 显示其一：

![侧栏（浅色）](oink-shell.webp)
{class="only-light"}

![侧栏（深色）](oink-shell.webp)
{class="only-dark"}

[data-bs-theme="dark"] .only-light,
:not([data-bs-theme="dark"]) .only-dark { display: none; }

class 由主题原样透传，供站点 CSS 使用。

输出形态

参数参考

属性行 {…}（块级图片之后紧接的一行）：

style、on*、alt、title、src 与其它任何键出现在属性行都会构建失败（alt、title、src 属于 Markdown 图片本身）。

限制与常见问题

• 图注不含 Markdown：所有公开字符串参数都是纯文本；富文本说明写在图片下方的段落中。
• title 不是图注：![a](b "c") 的 c 是悬停提示。
• 处理型图片只对资源生效：static/ 中的图需要处理时移到页面包或 assets/。
• 构建期不下载远程图片。
• 缩放不支持拖拽、平移、上一张 / 下一张；一组相关图片使用画廊。

相关

• 画廊 — 一组图片共用一个缩放对话框
• 书籍出版 — 图目录、xref 交叉引用
• 品牌外观 — 站点 logo 与 favicon 放哪
• 卡片 — 卡片上的图片

3 - 代码块

代码块是普通的 Markdown 围栏，高亮由 Hugo 内置的 Chroma 在构建期完成，浏览器里没有高亮器。用于命令、配置片段与源码：围栏信息行上的 {…} 属性决定标题栏、复制行为、行号与行锚点。图示类围栏（mermaid、echarts、filetree 等）不走这条路径，它们各有渲染钩子。

最简例子

```sql
SELECT datname, numbackends FROM pg_stat_database ORDER BY numbackends DESC;
```

SELECT datname, numbackends FROM pg_stat_database ORDER BY numbackends DESC;

没有属性的围栏同样有完整外壳与复制按钮。无标题栏时不渲染空白横条，复制按钮浮在右上角，鼠标悬停或焦点进入块内时出现，触屏设备上始终可见。外壳不显示语言名，lexer 名字只写入 data-language，供样式表与测试使用。

语言标记就是 Chroma 的 lexer 名。diff 围栏用 Chroma 的增删行样式呈现补丁，不需要额外组件：

```diff {title="hugo.yml 的改动"}
 params:
   ui:
-    sidebar_menu_compact: true
+    sidebar_menu_compact: false
     sidebar_menu_foldable: true
```

 params:
   ui:
-    sidebar_menu_compact: true
+    sidebar_menu_compact: false
     sidebar_menu_foldable: true

文件名标题

title 给块加一条可见标题栏，通常写文件名或路径。它同时成为这个块的无障碍名称。

```yaml {title="hugo.yml"}
markup:
  goldmark:
    parser:
      attribute:
        block: true
    renderer:
      unsafe: true
```

markup:
  goldmark:
    parser:
      attribute:
        block: true
    renderer:
      unsafe: true

filename 是 title 的历史别名，两个一起写会构建失败。

行号、起始行与高亮

lineNos 取 inline（行号与代码同一列）或 table（行号独立成列，可单独选中不被复制）。lineNoStart 改显示的起始编号。hl_lines 标记要强调的行，计数按围栏内的源码行，从 1 开始，与 lineNoStart 无关。

```ini {title="postgresql.conf" lineNos="inline" lineNoStart=120 hl_lines="2 4-5"}
shared_buffers = 8GB
max_connections = 200
work_mem = 64MB
wal_level = replica
max_wal_senders = 10
```

120shared_buffers = 8GB
121max_connections = 200
122work_mem = 64MB
123wal_level = replica
124max_wal_senders = 10

lineNos="table" 把行号放进独立的一列（两种模式下复制按钮都会剔除行号）：

```bash {title="部署三条命令" lineNos="table"}
./configure -c rich
./install.yml
pig ext install pg_duckdb
```

1
2
3

./configure -c rich
./install.yml
pig ext install pg_duckdb

tabWidth 决定制表符展开成几个空格，与 style 一样原样转交 Chroma。本站使用基于 class 的 Chroma 调色板（深浅色各一套），style 只在把 Hugo 切回内联样式模式时才生效。

长行换行

wrap=true 只改变显示：源码不变，复制出来的文本也不变。不加它时长行横向滚动。

```text {title="config/artifacts.env" wrap=true}
ARTIFACT_URL=https://repo.pigsty.io/pkg/infra/v3.6.0/infra-pkg-v3.6.0.el9.x86_64.tgz
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2
```

ARTIFACT_URL=https://repo.pigsty.io/pkg/infra/v3.6.0/infra-pkg-v3.6.0.el9.x86_64.tgz
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2

wrap=true 与表格行号不能共存：行号列与代码列是两个表格单元格，换行后会错位。写在一起构建失败，报错提示改用 lineNos="inline" 或去掉换行。

折叠长代码

collapse=N 让块初始只显示 N 行，底部给一个「显示全部 N 行」按钮。服务器输出完整代码，折叠是浏览器量出第 N 行位置后的视觉裁切：没有 JavaScript 时、读屏器中、打印时代码都是完整的。

```yaml {title="hugo.yml" collapse=8}
baseURL: https://oink.pgsty.com/
title: OINK
defaultContentLanguage: en
languages:
  en:
    languageName: English
    weight: 1
  zh:
    languageName: 简体中文
    weight: 2
params:
  offline_search: true
  ui:
    sidebar_menu_foldable: true
```

baseURL: https://oink.pgsty.com/
title: OINK
defaultContentLanguage: en
languages:
  en:
    languageName: English
    weight: 1
  zh:
    languageName: 简体中文
    weight: 2
params:
  offline_search: true
  ui:
    sidebar_menu_foldable: true

行数不超过 collapse 时按钮不出现。换行与折叠可以一起用：折叠测量的是第 N 个源码行节点的底边，换行的行不会被截断。

复制内容

默认复制整块源码。终端会话（console 与 shell-session 两个 lexer）默认只复制命令：带提示符的行留下，提示符本身与输出行去掉。下面这个块复制出来只有两条命令，没有 $ 也没有输出。

```console
$ pig ext list duckdb
name       version  category
pg_duckdb  1.0.0    OLAP
$ pig ext install pg_duckdb
INFO installing pg_duckdb
```

$ pig ext list duckdb
name       version  category
pg_duckdb  1.0.0    OLAP
$ pig ext install pg_duckdb
INFO installing pg_duckdb

要连提示符与输出一起复制就写 copy="all"。把 copy="command" 用在 bash、sh 之类普通 lexer 上会构建失败，因为它们分不出提示符、命令与输出。多行命令请在续行里写出续行提示符（通常是 >），否则那一行会被当成输出而排除。

会话 lexer 的块里一行提示符都没有时，复制按钮报失败：图标转为错误状态，控制台留一条错误，剪贴板不变。它不会退化成复制全文。

copy=false 关掉这一块的复制按钮，用于不应被抄走的反例片段：

```yaml {title="反例：属性行离开了它的块" copy=false}
params:
  ui:
    image_zoom: true   # 错：image_zoom 是一张表，不是布尔值
```

params:
  ui:
    image_zoom: true   # 错：image_zoom 是一张表，不是布尔值

整站关掉复制用 params.ui.code_copy: false，它优先于每个块自己写的 copy（见配置总览）。复制按钮只有图标，成功与失败会换图标并播报本地化状态；复制内容保留缩进、空行与 Unicode，去掉行号，末尾只留一个换行。

行链接与稳定 ID

把「看第 3 行」做成链接需要两步：给围栏一个明确的 id，再打开 anchorLineNos=true。行号随即变成锚点链接，锚点是 #<id>-<行号>。

```sql {id="ex-explain" title="explain.sql" lineNos="table" anchorLineNos=true}
EXPLAIN (ANALYZE, BUFFERS)
SELECT relname, n_live_tup
FROM pg_stat_user_tables
WHERE n_live_tup > 1000
ORDER BY n_live_tup DESC;
```

跳到 [第 4 行](#ex-explain-4)。

1
2
3
4
5

EXPLAIN (ANALYZE, BUFFERS)
SELECT relname, n_live_tup
FROM pg_stat_user_tables
WHERE n_live_tup > 1000
ORDER BY n_live_tup DESC;

跳到 第 4 行。

不写 id 时主题也会生成一个页面内唯一的 ID，但它依赖围栏在页面里的顺序，前面插入一个新围栏就会变。只有作者书写的 id 才是永久链接。ID 不能含空白与控制字符，也不能与页面上其它块的 viewport、标签、面板、标题、行锚点 ID 重复，重复即构建失败。

编号例

写书或长手册时给代码片段编号：num 加 caption，这个围栏就成了一条 Book「示例」目标，可以被 xref 引用，也会进入全书的示例目录。编号由作者书写，主题不自动计数；id 默认是 eg-<num>。

```sql {num="4-1" caption="按表统计膨胀率" #eg-bloat}
SELECT schemaname, relname, n_dead_tup, n_live_tup
FROM pg_stat_user_tables
WHERE n_dead_tup > n_live_tup * 0.2;
```

参见 {{< xref eg="4-1" anchor="eg-bloat" >}}。

SELECT schemaname, relname, n_dead_tup, n_live_tup
FROM pg_stat_user_tables
WHERE n_dead_tup > n_live_tup * 0.2;

参见 示例 4-1。

num 与 caption 必须成对出现，只写一个会构建失败；num 与标签页属性 tab 互斥。图、表、公式的编号写法与索引见书籍出版。

一组围栏做成标签页

连续几个带 tab 的围栏会在浏览器里合成一个标签页集，第一个围栏上的 group 让它可分享、可同步、可记住选择。

```bash {tab="Homebrew" group="oink-install" value="brew"}
brew install hugo
```
```bash {tab="APT" value="apt"}
sudo apt install hugo
```

brew install hugo

sudo apt install hugo

完整规则（分组语法、URL hash、跨组同步、正文标签页）在标签页。

易错写法

• 在文档里展示 shortcode：围栏不阻止 Hugo 解析，写在代码块里的 {{< tabs >}} 仍会执行。要让它原样显示，在两侧定界符的内侧各加一对注释符号，写成 {{</* tabs */>}}，百分号形式对应 {{%/* steps */%}}。本页每一处展示 shortcode 的地方都是这么写的。
• 围栏里套围栏：外层用四个反引号、内层三个，本页每一段「源码」都是这么写的；内层还有围栏时外层再加一个。
• 属性写在信息行上：围栏的属性跟在开栏那一行的语言后面，表格与图片的属性才写在块的下一行。写到下一行会变成正文里一段可见的花括号。
• 未知属性会失败，不会被忽略，错误信息里列出允许的名字。style、srcdoc 与 on* 被拒绝；data-td-code* 前缀以及 data-language、data-line-count、data-collapse-lines 是主题的保留名，写上去同样构建失败。
• 列表项里的围栏：缩进要与列表项内容对齐（1. 之后恒定三个空格），否则围栏会脱离列表。

输出形态

没有复制或折叠控件的页面不加载 code-block.js；打印、Markdown 与 RSS 输出不加载。

参数参考

开栏那一行、语言之后的 {…} 里，OINK 自己的属性：

title、filename 与 label 已经为块生成了无障碍名称与 role="group"。它们中的任意一个与 aria-label、aria-labelledby 或 role 同时出现都会构建失败；这三个属性只在块没有标题也没有 label 时可以透传。

同一行还能写 Chroma 选项，主题原样转交 Hugo：

限制与常见问题

• 不换高亮器：没有 Shiki、Twoslash、浏览器端高亮，也没有可执行的代码演练场。补丁用 diff 围栏，Chroma 的 .gi/.gd 就是增删行的样式。
• copy="command" 只认会话 lexer：写在别的语言上是构建错误，不会退化成复制全部。
• 自动生成的 ID 不是永久链接：要发链接就写 id。
• mermaid、math、chem、markmap、plantuml、echarts、infographic、checksums、filetree、gallery 不是代码块：它们有各自的渲染钩子，不套这层外壳，也没有复制按钮。

相关

• 标签页 — 相邻围栏合成标签页的完整规则
• 引用 — 把仓库里的真实文件当代码块插进来
• 书籍出版 — 编号示例、交叉引用与示例目录
• 打印支持 — 长代码在打印里的形态

4 - 标签页

标签页并列等价的几种写法：包管理器、发行版、YAML / TOML / JSON、环境变量与配置项。有先后的步骤、互不相关的内容不适合标签页，读者一次只看见其中一个。

原生形态是给相邻的块加 tab 属性。正文（多个段落、列表、提示块）要做成标签页时才用 tabs/tab shortcode。两种形态共用一个运行时、一套 DOM 与一样的键盘行为。

最简例子

连着写两个带 tab 的围栏，中间只隔空行。

```bash {tab="Homebrew"}
brew install hugo
```
```bash {tab="Debian / Ubuntu"}
sudo apt install hugo
```

brew install hugo

sudo apt install hugo

服务器输出两个带标题的代码块，没有面板被隐藏；页面加载后运行时把相邻的同类块重组为标签页。在 GitHub 上、打印时、关闭 JavaScript 时，读者看到的是连续两块完整内容。

分组：链接、同步与记忆

只在第一个块上写 group，这一组就有了公开的 URL hash #<group>-<value>、页内同步与浏览器持久化；分组内的每个块都要写 value。

```bash {tab="npm" group="pkgmgr" value="npm"}
npm create hugo-site@latest
```
```bash {tab="pnpm" value="pnpm"}
pnpm create hugo-site
```
```bash {tab="Yarn" value="yarn"}
yarn create hugo-site
```

npm create hugo-site@latest

pnpm create hugo-site

yarn create hugo-site

value 是机器值（^[a-z0-9][a-z0-9_-]*$），tab 是给人看的标签名，两者互不相干。上面这组的 pnpm 面板对应的 hash 是 #pkgmgr-pnpm，带这个 hash 访问本页会直接选中它。

同组联动

下面这组用了同一个 group="pkgmgr"。在上面那组切换包管理器，这组会跟着切；在这组切换，上面那组也跟着切。选择写入 localStorage 的 td-tabs:v1:pkgmgr 键，在其它页面同组的标签页上仍然生效。

```bash {tab="npm" group="pkgmgr" value="npm"}
npm run build
```
```bash {tab="pnpm" value="pnpm"}
pnpm build
```

npm run build

pnpm build

这组没有 yarn 面板。同步时缺哪个值就保持不动，不会出现「一组没有选中项」的状态。初始选哪个的优先级是：URL hash，存储的值，shortcode 的 default 或第一个块，第一个标签。带 hash 打开页面只切换，不覆盖读者已经存下的偏好。

表格也能做标签页

同一套属性写在表格的属性行上，连着的表格就组成一组标签页。

| 参数 | 默认值 |
| --- | --- |
| `shared_buffers` | 25% RAM |
| `max_connections` | 100 |
{tab="PostgreSQL 18" group="pgver" value="pg18"}

| 参数 | 默认值 |
| --- | --- |
| `shared_buffers` | 128MB |
| `max_connections` | 100 |
{tab="PostgreSQL 13" value="pg13"}

围栏与表格是两种块类型，相邻也不会合成同一组：一组标签页里只能全是围栏或全是表格。两者混排使用下面的 shortcode 形态。

标签名与文件名共存

围栏的 tab 和 title 可以一起写：标签名进标签栏，文件名标题栏留在面板里。

```yaml {tab="YAML" title="hugo.yml" group="conffmt" value="yaml"}
params:
  ui:
    sidebar_menu_foldable: true
```
```toml {tab="TOML" title="hugo.toml" value="toml"}
[params.ui]
sidebar_menu_foldable = true
```

params:
  ui:
    sidebar_menu_foldable: true

[params.ui]
sidebar_menu_foldable = true

单独一个块只是带标题的块

一个块要凑够两个相邻的同类块才会变成标签页。落单的块保留标题，不会变成只有一个标签的标签栏。

```ini {tab="只有这一块"}
listen_addresses = '*'
```

listen_addresses = '*'

块之间只允许空行。三种情况会断开一组：中间隔了正文（段落、标题、列表都算）；中间有一条 HTML 注释，<!-- prettier-ignore-end --> 是常见的一处；后一个块自己写了 group，一组里只有第一个块可以带 group。

正文标签页

面板里要放段落、列表、提示块或多个块时，用 tabs/tab shortcode。正文是完整的 Markdown。

{{< tabs group="deploy" default="pages" label="部署方式" >}}
{{< tab label="GitHub Pages" value="pages" >}}
仓库自带 `.github/workflows/`，推到 `main` 就会构建并发布。

> [!NOTE]
> `baseURL` 要写成仓库的 Pages 地址。
{{< /tab >}}
{{< tab label="Cloudflare Pages" value="cloudflare" >}}
在 Cloudflare 控制台里连接仓库，构建命令：

```bash
hugo --gc --minify
```
{{< /tab >}}
{{< /tabs >}}

hugo --gc --minify

default 指定初始选中的面板，它必须是某个子项的 value，并且需要 group。没有 group 时不能写 value，主题自动生成 tab1、tab2 等值，这组标签页只在本地切换，不动 URL 也不写存储。shortcode 形态比属性形态严格：写错的地方在构建期就报出来，不留到浏览器里。

输出形态

只有用到标签页的页面才加载 tabs.js；打印、Markdown 与 RSS 输出不加载。

参数参考

写在围栏信息行或表格属性行上的属性：

tabs shortcode：

tab shortcode：

行为约定：面板 ID 在分组里是 <group>-<value>，同一页出现第二组同名 group 时后续各组的 ID 加 -2、-3 后缀（深链目标始终是第一组），未分组时由主题生成；存储键是 td-tabs:v1:<group>；用户点击或按键会用 replaceState 更新 hash 并写入存储，带 hash 访问只切换不写入。键盘上左右方向键（感知 RTL）与 Home/End 移动并激活标签，焦点停留在标签上。

限制与常见问题

• 构建失败的写法：属性形态里 value 缺 group、group 或 value 缺 tab、tab 与编号属性 num 同时出现；shortcode 形态里一组内 value 重复、tabs 没有 tab 子项、子项之间夹着正文、default 不匹配任何子项的 value。
• 属性形态的分组错误不中断构建，只在浏览器控制台留警告：分组内漏写 value 时整组丢掉 group，退化成只在本地切换的标签页，hash、同步与持久化都没有；value 重复时整组跳过，那几个块保持为各自带标题的块。
• 围栏与表格不会混成一组，正文与代码混排请用 shortcode 形态。
• 标签页不是折叠块。只想收起长输出用 > [!DETAILS]（见提示块）。
• 同名 group 是全站共享的：读者在 A 页选了 pnpm，B 页同组的标签页也会是 pnpm。这是它的用途，也意味着 group 名要按含义取，不用 tabs1 这种。

相关

• 代码块 — 围栏的其余属性（标题、复制、行号、折叠）
• 表格 — 表格属性行的其余取值
• 提示块 — 折叠而不是并列时用它
• 步骤 — 步骤里可以放标签页

5 - 表格

表格是普通的 GFM 管道表格。主题的表格渲染钩子把每张表包进一块可横向滚动的区域，表格下面那一行 {…} 属性决定它是哪一种表：带标题的表、兼容矩阵、参数表、编号表或标签页。合并单元格、排序与筛选不在能力范围内，需要它们的场景请改换呈现方式。

最简例子

不写属性行就是一张普通表。对齐方式照旧来自分隔行，表头单元格是 th scope="col"。

| 组件 | 端口 | 用途 |
| --- | :---: | --- |
| PostgreSQL | 5432 | 数据库 |
| Pgbouncer | 6432 | 连接池 |
| Patroni | 8008 | 高可用编排 |

宽表格自己滚动

列太多的表不会把页面撑宽，它在自己的区域里横向滚动。这块区域可以用键盘聚焦：Tab 停入后方向键滚动，无障碍名称是本地化的「可横向滚动的表格」。

| 集群 | 角色 | 版本 | 状态 | 延迟 | 连接数 | 大小 | 备份 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| pg-meta | primary | 18.1 | running | — | 42 | 12 GB | 2026-08-17 |
| pg-test | replica | 18.1 | streaming | 12 ms | 8 | 12 GB | 2026-08-17 |

表格标题

{caption="…"} 加一个可见的 <caption>，纯文本，不给表编号。

| 条目 | 取值 |
| --- | --- |
| 主题版本 | v0.6.0 |
| Hugo 下限 | 0.160.1 Extended |
| 许可证 | Apache-2.0 |
{caption="本站当前使用的主题事实"}

兼容矩阵

{.matrix} 用于「行 × 列 = 支持与否」的对照表：第一列成为行表头（th scope="row"），滚动时表头行与第一列吸附不动，其余单元格居中，分隔行另有对齐时以分隔行为准。✅ 与 ❌ 是作者写的字符，主题不解析它们。

| OS / PG | PG18 | PG17 | PG16 | PG15 | PG14 |
| --- | :---: | :---: | :---: | :---: | :---: |
| EL 9 | ✅ | ✅ | ✅ | ✅ | ✅ |
| EL 8 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Debian 13 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Ubuntu 24.04 | ✅ | ✅ | ✅ | ✅ | ❌ |
{.matrix}

用整个画布

{.full-width} 让表格越出正文栏宽，占满文章可用的宽度。适合列多但每列都短的表。

| 语言 | 代码 | 侧栏 | 搜索 | 目录 | 打印 | 状态 |
| --- | --- | --- | --- | --- | --- | --- |
| 简体中文 | `zh` | ✅ | ✅ | ✅ | ✅ | 已审校 |
| English | `en` | ✅ | ✅ | ✅ | ✅ | 已审校 |
{.full-width}

参数表

{.fields} 把表格变成定义列表：第一列是名称，最后一列是说明，中间列是元数据。它是记录配置项、命令参数、API 字段的形态，写法见参数表。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `offline_search` | boolean | `false` | 构建本地搜索索引 |
| `page_width` | string | `normal` | 正文栏宽度 |
{.fields meta="type default"}

编号表

写书或长手册时给表编号：num 加可选的 #id 与 caption。表格会被包进一个带本地化「表 N.」标签的 <figure>，并注册成 Book 目标，可以被 xref 引用、进入全书表格目录。编号由作者书写，主题不自动计数；id 缺省是 tbl-<num>。

| 隔离级别 | 脏读 | 不可重复读 | 幻读 |
| --- | --- | --- | --- |
| 读已提交 | 否 | 是 | 是 |
| 可重复读 | 否 | 否 | 是 |
| 可串行化 | 否 | 否 | 否 |
{#tbl-iso num="9-1" caption="PostgreSQL 各隔离级别允许的异象"}

参见 {{< xref tbl="9-1" anchor="tbl-iso" >}}。

参见 表 9-1。

表格做成标签页

连着的表格加 {tab="…"} 就组成一组标签页，规则与相邻围栏一致：第一张表上的 group 启用 hash、同步与持久化，此后每张表都要 value。完整规则见标签页。

| 目录 | 内容 |
| --- | --- |
| `content/` | 页面 |
| `data/` | 首页与发布数据 |
{tab="内容" group="repo-layout" value="content"}

| 目录 | 内容 |
| --- | --- |
| `assets/` | SCSS 与图片资源 |
| `static/` | 原样拷贝的文件 |
{tab="资源" value="assets"}

输出形态

表格不加载任何脚本。

参数参考

表格下一行的属性行：

style、on* 与任何其它键都会让构建失败。

限制与常见问题

• 互斥规则：.fields 不能和 .matrix、.full-width 或 num 一起用；num 与 tab 互斥；group/value 需要 tab；meta 需要 .fields。
• 属性行必须紧贴表格：中间空一行，它就变成正文里一段可见的花括号。Markdown 格式化工具常移动这一行，把它包进 <!-- prettier-ignore-start --> / <!-- prettier-ignore-end -->。
• 没有合并单元格、没有排序、没有筛选：GFM 管道表格能表达的就是全部。需要合并表头的复杂表请拆成两张表或改成一张矩阵。
• 单元格里放不下块内容：多段说明、列表、围栏要用 fields/field shortcode。
• .matrix 的居中由 CSS 实现：分隔行里写了对齐就以分隔行为准。

相关

• 参数表 — {.fields} 的完整写法
• 标签页 — 相邻表格组成标签页
• 书籍出版 — 编号表、交叉引用与表格目录
• 代码块 — 属性写在信息行而不是下一行

6 - 参数表

参数表（Fields）把「一串具名值 + 元数据 + 说明」渲染成响应式定义列表：名称独占一行，类型、是否必填、默认值是名称旁边的小字，说明另起一行，每一条自带锚点。用于配置项、命令参数与 API 字段。要按同一批列横向比较很多行时用普通表格，内容是操作顺序时用步骤。

写法有两种：普通表格加 {.fields}（默认选它），以及 fields/field shortcode（说明需要多个段落、列表或代码块时才用）。两种形态渲染出相同的条目。

最简例子

一张至少两列的管道表格，下一行写 {.fields}。第一列是名称，最后一列是说明，中间每一列都是元数据，标签就是表头文字本身。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `offline_search` | boolean | `false` | 构建本地搜索索引并启用命令面板 |
| `offline_search_max_results` | integer | `10` | 搜索结果条数上限 |
| `page_width` | string | `normal` | 正文栏宽度，可选 `narrow` `normal` `wide` |
{.fields}

这里的元数据显示成「表头: 值」。主题不推断表头的含义，类型 只是一个标签；要让它变成标准芯片见下一节。单元格接受行内 Markdown（代码、强调、链接），空的中间单元格省略。

语义列 meta=

meta 按顺序说明每一个中间列扮演什么角色：type（类型）、required（必填）、default（默认值），或者 -（保留表头当标签）。有了它，表格形态渲染出的芯片与 shortcode 形态一致。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `baseURL` | string | 是 | | 站点地址，含子路径 |
| `title` | string | 是 | | 站点名，出现在顶栏与页签 |
| `defaultContentLanguage` | string | | `en` | 默认语言，决定无前缀路径属于哪种语言 |
{.fields meta="type required default"}

规则：

• meta 必须为每一个中间列写一个角色，个数等于总列数减二；写多写少都构建失败。
• required 列是「非空即真」：单元格里写「是」「yes」「✔」都一样，渲染出来的是不翻译的 required 芯片；留空就不显示。
• type 与 default 单元格如果本身没有行内标记，会自动套上代码格式，与 shortcode 形态对齐。
• 三种语义芯片按 type、required、default 的顺序显示，与列的顺序无关；- 列跟在后面，按列顺序排。

- 可以和语义角色混用，用来保留一列自定义标签：

| 环境变量 | 类型 | 作用域 | 说明 |
| --- | --- | --- | --- |
| `HUGO_MODULE_WORKSPACE` | string | 构建 | 指向 `go.work`，让主题从本地 checkout 解析 |
| `HUGO_ENV` | string | 构建 | 设为 `production` 时启用压缩与指纹 |
{.fields meta="type -"}

标签与容器 ID

caption 给整张表加一个可见标签（同时是无障碍名称），id 命名外层容器，方便从别处链接过来或写站点 CSS。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enable` | boolean | `false` | 打开图片缩放 |
| `selector` | string | `.td-content` | 扫描候选图片的根选择器 |
{.fields caption="params.ui.image_zoom" id="zoom-params" meta="type default"}

每一条都能单独链接

每个条目获得一个 field-<名称> 形式的锚点，鼠标移上去时名称右边出现自链接图标。上面第一张表里的 page_width 就是 #field-page_width，回答问题时可以把这一行的链接单独发出去。

同一页里重名的字段按 -2、-3 顺延，规则与 Goldmark 处理重名标题一致。锚点只在 HTML 里生成：打印和 RSS 会把很多页拼成一个文档，页内锚点在那里会冲突。

shortcode 形态

说明需要多个段落、列表或代码块时，表格单元格装不下，改用 fields/field：

{{< fields label="pig 命令常用参数" >}}
{{< field name="--config" type="path" required=true >}}
配置文件路径。相对路径按当前工作目录解析。

如果同时设置了 `PIG_CONFIG` 环境变量，命令行参数优先。
{{< /field >}}
{{< field name="--log-level" type="string" default="info" >}}
日志级别，从低到高：

- `debug`：打印每一次远程调用
- `info`：默认值
- `error`：只在失败时输出
{{< /field >}}
{{< field name="--dry-run" type="boolean" default=false >}}
只打印将要执行的动作，不改任何东西：

```bash
pig ext install pg_duckdb --dry-run
```
{{< /field >}}
{{< /fields >}}

required=true 与 default=false 是布尔值，不加引号。default 接受任何标量：default=0、default="" 都会如实显示（空字符串显示成 ""），不写 default 就不显示这一项。每个 field 必须有非空正文，并且必须是 fields 的直接子项。

两种形态的选择

表格形态在 GitHub 上仍然是一张可读的表，OINK 的 Markdown 输出也保持表格原样，这是默认选它的理由。

输出形态

不加载任何脚本。

参数参考

表格属性行（写在表格下一行）：

fields shortcode：

field shortcode：

限制与常见问题

• 第一列必须非空，且在同一张表内唯一：重名或空名构建失败。
• .fields 不能与 .matrix、.full-width、num 组合，meta 不能用在没有 .fields 的表上。
• 表格单元格里放不下块内容：需要段落、列表、围栏就换 shortcode 形态。
• required 与 default 是不翻译的 API 词汇，在所有语言下都显示英文，它们是契约词，不是界面文案。
• 暂不支持 kind、since、deprecated、location、字段级链接与嵌套结构，也不会在构建时解析 TypeScript 或 OpenAPI schema。

相关

• 表格 — 属性行的其它取值与互斥规则
• 配置总览 — 站点参数全表就是用参数表写的
• 页面参数 — front matter 全表
• 步骤 — 顺序动作不要写成参数表

7 - 步骤

步骤（Steps）是带编号圆点与竖线的有序列表：一个普通有序列表，加一行 {.steps} 标记，编号圆点与串起它们的竖线由 CSS 绘制，不加载脚本。用于有先后的操作流程。并列而无先后的内容用普通列表或卡片。

写法有两种：有序列表加 {.steps}（默认选它），以及 {{% steps %}} shortcode，每一步要有自己的标题、标题还要进右侧目录时用它。

最简例子

每一项都写 1.，让 Markdown 自己数。这样插入、删除、调换步骤都不用手改编号，而且内容缩进恒定是三个空格。

1. 安装 Hugo Extended
1. 克隆文档站
1. 启动本地预览
{.steps}

1. 安装 Hugo Extended
2. 克隆文档站
3. 启动本地预览

{.steps} 必须紧贴列表最后一行，中间空一行它就会变成正文里一段可见的花括号。

步骤内容

列表项里可以放任何块级内容：段落、代码围栏、提示块、表格、嵌套列表、图片。缩进对齐到列表项的内容列（三个空格）即可。

1. 克隆文档站，它本身就是主题的完整示例。

   ```bash
   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs
   ```

1. 启动本地服务器。

   ```bash
   hugo server
   ```

   > [!NOTE]
   > 首次构建会通过 Go 模块代理拉取主题，需要本机安装 Go。

1. 替换三处内容，它就是你的站点。

   | 位置 | 替换为 |
   | --- | --- |
   | `hugo.yml` 的 `title` | 你的站名 |
   | `hugo.yml` 的 `baseURL` | 你的域名 |
   | `content/` | 你的内容 |
{.steps}

1. 克隆文档站，它本身就是主题的完整示例。

   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs

2. 启动本地服务器。

   hugo server

   说明

   首次构建会通过 Go 模块代理拉取主题，需要本机安装 Go。

3. 替换三处内容，它就是你的站点。

   位置	替换为
   hugo.yml 的 title	你的站名
   hugo.yml 的 baseURL	你的域名
   content/	你的内容

{{< … >}} 形式的 shortcode（标签页、卡片、徽章等）也可以写在列表项里；{{% … %}} 形式不行，见下面的限制。

一步里按平台分开

某一步在不同平台上命令不同时，把带 {tab=} 的围栏并排写进那个列表项，它们照样会合成标签页。

1. 安装 Hugo Extended。

1. 安装依赖：

   ```bash {tab="EL / RHEL" group="stepdemo" value="rpm"}
   sudo dnf install golang git
   ```
   ```bash {tab="Debian / Ubuntu" value="deb"}
   sudo apt install golang-go git
   ```

1. 运行 `hugo server` 预览。
{.steps}

1. 安装 Hugo Extended。

2. 安装依赖：

   EL / RHEL

   sudo dnf install golang git

   Debian / Ubuntu

   sudo apt install golang-go git

3. 运行 hugo server 预览。

接着上一组往下编号

正文隔断了一组步骤时，把新一组的第一项写成它实际的序号，Markdown 会输出 start，编号从那里继续（支持到 40）。

4. 配置 `baseURL` 与部署工作流。
1. 推送到 `main`，等待 GitHub Actions 构建完成。
{.steps}

4. 配置 baseURL 与部署工作流。
5. 推送到 main，等待 GitHub Actions 构建完成。

带标题的步骤

步骤本身很长、每一步该有个能被链接和被目录收录的标题时，用 {{% steps %}}：它的正文是页面级 Markdown，里面的每一个直接子标题就是一步，正文不用缩进。下面三步的标题就在这一页的右侧目录里。

{{% steps %}}

### 安装工具链 {#install-toolchain}

需要 Hugo Extended ≥ 0.160.1 与 Go。

### 启动服务器 {#run-server}

{{< tabs group="oink-os" default="macos" >}}
{{< tab label="macOS" value="macos" >}}
`brew install hugo go`
{{< /tab >}}
{{< tab label="Debian" value="debian" >}}
`sudo apt install hugo golang-go`
{{< /tab >}}
{{< /tabs >}}

### 发布 {#publish}

推送到 `main`，仓库自带的工作流会构建并发布。

{{% /steps %}}

它是主题里唯一的 {{% … %}} shortcode。百分号形式的正文交给 Goldmark 当页面级 Markdown 处理：只有这样，里面的标题才能进目录，里面才能放 tabs、cards、fields 这些容器 shortcode。代价是它自己不能嵌进列表项，也不能嵌进另一个百分号容器。

同一组步骤的标题保持同一层级，不要把一个 steps 套进另一个里。

两种形态的选择

输出形态

不加载脚本；关闭 JavaScript 后呈现不变。

参数参考

两种形态都没有参数，只有写法约定：

限制与常见问题

• 列表项里不能写 {{% … %}}：百分号 shortcode 的多行输出会把列表截断。要在步骤里放容器就整组改用 shortcode 形态。
• {{% steps %}} 不能放进列表项，也不能套在另一个百分号容器里。
• 标记要紧贴列表：{.steps} 与列表之间不能有空行；经过 Prettier 之类的格式化工具时，把它包进 <!-- prettier-ignore-start --> / <!-- prettier-ignore-end -->。
• {.steps} 只对有序列表有效：写在 - 开头的无序列表上不会有编号。
• 步骤不折叠、不记进度：没有「已完成」状态，也没有展开收起。

相关

• 标签页 — 按平台分开的命令
• 提示块 — 某一步里的前提与警告
• 代码块 — 步骤里的命令
• 卡片 — 步骤做完之后的「下一步」

8 - 卡片

卡片（Cards）是一组并列的链接：每张卡片一个链接标题加一句描述，网格随容器宽度自适应。适合栏目首页、「接下来读什么」与几条并列路径的入口。不适合排版正文段落（用普通段落）或做图片墙（用画廊）。

最简例子

带 {.cards} 的链接列表就是卡片。链接是标题，— 之后是描述。

- [快速上手](/zh/docs/start/) — 克隆这个文档站，删掉不需要的页面，替换为你的站点信息。
- [创作内容](/zh/docs/write/) — 页面怎么组织、front matter 有哪些键。
- [定制站点](/zh/docs/customize/) — 导航、搜索、品牌、多语言。
{.cards}

• 快速上手 — 克隆这个文档站，删掉不需要的页面，替换为你的站点信息。
• 创作内容 — 页面怎么组织、front matter 有哪些键。
• 定制站点 — 导航、搜索、品牌、多语言。

整张卡片是点击热区，不只是标题文字。没有 columns 参数：列数由容器宽度决定，窄屏收成一列。

只有标题的卡片

描述可以省略。一行一个链接，{.cards} 收尾。

- [提示块](/zh/docs/components/callout/)
- [标签页](/zh/docs/components/tabs/)
- [步骤](/zh/docs/components/steps/)
- [参数表](/zh/docs/components/fields/)
{.cards}

• 提示块
• 标签页
• 步骤
• 参数表

松散列表与多段描述

一句话装不下时改用松散列表：链接单独一段，描述另起一段，列表项之间空一行。标题独占一行，描述在标题下方。{.cards} 仍然紧贴最后一段，中间 不能有空行。

- [页面参数](/zh/docs/write/frontmatter/)

  每个页面参数在这里有唯一定义：类型、默认值、取值范围，以及讲它的那一页。

- [配置总览](/zh/docs/customize/config/)

  站点参数按功能分组，同样每行反向链接到讲它的指南页。
{.cards}

• 页面参数

  每个页面参数在这里有唯一定义：类型、默认值、取值范围，以及讲它的那一页。

• 配置总览

  站点参数按功能分组，同样每行反向链接到讲它的指南页。

图标与徽章

链接列表不支持图标、徽章、图片与多段描述，这些用 cards / card shortcode。icon 是恰好一对 Font Awesome class，badge 是一段纯文本。

{{< cards >}}
{{< card title="快速上手" link="/zh/docs/start/" icon="fa-solid fa-rocket" badge="从这里开始" >}}
Fork 文档站本身，十分钟内完成本地预览。
{{< /card >}}
{{< card title="发布与下载页" link="/zh/docs/write/releases/" icon="fa-solid fa-box-open" badge="v0.5" >}}
`release` 事实记录 + 资产表 + 校验和，全部本地生成。
{{< /card >}}
{{< card title="键盘导航" link="/zh/docs/customize/keyboard/" icon="fa-solid fa-keyboard" >}}
全站快捷键与焦点顺序。
{{< /card >}}
{{< /cards >}}

图标格式不符（不是 fa-solid fa-xxx 这样的一对 class）时构建失败，不会静默丢弃。

Markdown 正文

card 的正文按页面级 Markdown 渲染：行内代码、强调、链接、列表都可以。title、badge 这些参数是纯文本，不解析 Markdown。

{{< cards >}}
{{< card title="Hugo Module" icon="fa-brands fa-golang" >}}
`hugo mod get github.com/pgsty/oink`。推荐方式，升级只需改一行版本号。
{{< /card >}}
{{< card title="Git Submodule" icon="fa-solid fa-code-branch" >}}
无需安装 Go：

- `git submodule add`
- 主题落在 `themes/oink`
{{< /card >}}
{{< /cards >}}

不写 link 的卡片渲染成加粗标题，不生成链接。

带图片的卡片

image 与 ![alt](src) 的解析顺序一致：页面资源 → 全局资源 assets/ → 静态路径 /images/… → 远程 URL。本地资源带上固有尺寸，避免加载跳版。

image 必须配一个替代文字来源：image_alt="…"（有信息的图）或 decorative=true（纯装饰）。两个都写、两个都不写都会构建失败。

{{< cards >}}
{{< card title="OINK 文档外壳" link="/zh/docs/about/features/" image="images/content-primitives/oink.webp" image_alt="OINK 文档页面：侧栏、正文与目录三栏" >}}
侧栏、正文、目录，三栏可以单独关闭。
{{< /card >}}
{{< card title="发布说明" link="/zh/docs/write/releases/" image="/images/releasenote.webp" decorative=true >}}
装饰性封面：`decorative=true` 输出空 alt，读屏器会跳过它。
{{< /card >}}
{{< /cards >}}

OINK 文档外壳

侧栏、正文、目录，三栏可以单独关闭。

发布说明

装饰性封面：decorative=true 输出空 alt，读屏器会跳过它。

卡片图片不参与图片缩放，整张卡片本身已经是链接。

栏目首页的自动卡片

栏目首页（_index.md）不需要手写卡片列表：主题读子页的 title、description、icon 自动生成一组卡片。本站在 hugo.yml 中全局启用：

params:
  ui:
    section_index: cards # list | cards

单个栏目可以在自己的 front matter 里覆盖，也可以用 cascade 把选择推给整棵子树：

section_index: list

自动卡片与手写卡片使用同一套 td-content-card 样式，区别只在数据来源。栏目首页不要手写子页清单：手写清单会与侧栏不同步。要排的内容不是本栏目的子页时（例如混合站外链接、跨栏目推荐），才在正文里手写卡片。相关键的完整定义见配置总览。

两种形态的选择

链接列表在 GitHub 上仍是一个链接列表，shortcode 不是。能用原生形态时用原生形态。

输出形态

参数参考

原生形态：

card 的参数（cards 自身不接受任何参数）：

没有 cols、columns、accent、desc、color 参数；未知参数一律构建失败。

限制与常见问题

• {.cards} 只认无序列表：有序列表加了这个标记不会变成卡片。
• {.cards} 必须紧贴列表：中间空一行、或缩进进列表项，标记被静默丢弃，构建不报错，列表仍是列表。渲染结果不是卡片时先检查这一行。
• card 只能待在 cards 里：单独使用、或放进别的 shortcode，构建失败并指出位置。
• 列数不可配：网格按容器宽度自适应，只有栏目首页的自动卡片能用 params.ui.section_index_columns 指定列数。
• 卡片不放长文：描述超过两行时改用正文段落或提示块。

相关

• 参数表 — 同样有原生 / shortcode 两种形态
• 画廊 — 一组图片的网格
• 徽章 — 行内状态标签
• 组织内容 — 栏目、权重与首页
• 配置总览 — section_index 等站点参数

9 - 文件树

文件树（FileTree）是一个 filetree 围栏，围栏正文就是目录清单：缩进表示层级，结尾的 / 表示目录，# 之后是注释。适合解释一份目录结构里与读者有关的那部分，并逐条加上说明。需要读者逐字复制的清单用普通代码块。

最简例子

```filetree
- content/
  - _index.zh.md
  - docs/
  - blog/
- hugo.yml
- go.mod
```

项目符号（-、*、+）可以省略，效果相同。有子项的条目是目录；没有子项时，结尾的 / 告诉主题它是目录。

加注释

每行第一个前面带空白的 # 之后是注释，渲染成对齐的右列。注释是纯文本，里面的 Markdown 按字面显示；要一个字面井号就写 \#。

```filetree
- content/          # 全部页面，中英双语同目录
  - docs/          # 你正在读的这棵文档树
  - blog/           # 发布说明与文章
- assets/scss/      # 站点自己的 SCSS，覆盖主题变量
- layouts/          # 站点级模板覆盖，越少越好
- static/images/    # 不需要构建期处理的图
- hugo.yml          # 站点配置：语言、菜单、params.ui
```

注释列的起点在构建期算出，由最宽的一行决定，因此每行的 # 从同一列开始，与源码里是否对齐无关。注释列最多占面板的右半边，最少占三成。中间的虚线是分隔条，可以拖动，也可以用 Tab 聚焦后按方向键调整（Home / End 到两端）。

过长的名称与注释各自在本列内用省略号截断，鼠标悬停时由 title 提示完整文本。分隔条是文件树唯一的 JavaScript，只有 带注释 的树才加载它。

```filetree {title="两列都发生截断"}
- runbooks/
  - a-deliberately-long-runbook-filename-for-a-failover-drill.md  # 同样超长的注释，写在一行里，因此必须在注释列内截断
  - restart.md                                                    # 短名字
```

标题栏

围栏属性 {title="…"} 在树上方渲染一条标题栏；不写时没有标题栏。

```filetree {title="oink.pgsty.com 仓库根目录"}
- content/          # 页面
- assets/           # 参与构建的资源
- data/             # 首页、Landing、下载页的数据
- layouts/          # 模板覆盖
- static/           # 原样拷贝的文件
- tests/            # Playwright 与 node --test
- hugo.yml
- go.mod            # 用 Hugo Module 引入主题
- Makefile          # make d / make b / make c
```

缩进与层级

层级由缩进决定。两个空格、四个空格、制表符（按四列计算）都可以，同一棵树内不要求统一，条件是每次退回的层级此前已经打开过。tree 命令的输出可以整段粘贴，包括开头的根目录行与结尾的统计行，统计行会被丢弃。

```filetree
content/docs
├── about
│   ├── _index.zh.md
│   └── features.zh.md
├── components
│   ├── filetree.zh.md
│   └── image
│       └── index.zh.md
└── _index.zh.md

3 directories, 5 files
```

退回到未打开过的缩进层级时构建失败，报错里带围栏内的行号。

折叠与显式类型

有子项的目录默认展开，{open=false} 使其初始收起。目录用原生 <details> 渲染，键盘可操作，不需要 JavaScript。open 只能写在目录上。没有子项、名字也不以 / 结尾的条目按文件处理，{type=dir} 覆盖这个判断，{type=file} 同理。

```filetree {title="内容目录"}
- content/
  - docs/                # 新文档树
    - components/         # 22 个组件页        {open=false}
      - callout.zh.md
      - filetree.zh.md
      - image/            # 页面包：正文 + 图  {type=dir}
    - customize/          # 站点级配置          {open=false}
      - config.zh.md
  - blog/
    - release.zh.md
```

图标与配色

图标默认按名字推断：目录用文件夹图标，随开合切换；文件先按完整文件名匹配（LICENSE、Makefile、go.mod、package.json、.gitignore 等），再按扩展名匹配（md yml toml json sh py go js sql css png svg pdf zip 等），都不匹配时用普通文件图标。

{icon=…} 覆盖它，取值是恰好一对 Font Awesome class。{tone=…} 给图标上色，取值与徽章相同：neutral info success warning danger。

```filetree {title="部署目录：权限与要点"}
- /etc/pigsty/                 # 0755 root:root · 配置根目录        {icon="fa-solid fa-server" tone=info}
  - pigsty.yml                 # 0644 root:root · 集群清单
  - ca/                        # 0700 root:root · 自签 CA，不要提交进 Git  {icon="fa-solid fa-lock" tone=danger open=false}
    - ca.key                   # 0600 root:root
- /var/lib/pgsql/18/data/      # 0700 postgres:postgres · 数据目录   {tone=warning}
  - postgresql.conf            # 0600 postgres:postgres
- /usr/bin/pig                 # 0755 root:root · 命令行工具         {icon="fa-solid fa-terminal" tone=success}
```

tone 只给图标上色，不改文字。颜色是补充，含义写在名字或注释里。

条目链接

条目名写成 [名字](链接) 即为链接。站内路径、相对路径、http(s): 都可以，URL 校验与其它组件是同一套。

```filetree {title="本站的组件页"}
- content/docs/components/
  - [callout.zh.md](/zh/docs/components/callout/)     # 提示块
  - [filetree.zh.md](/zh/docs/components/filetree/)   # 当前页面
  - [gallery.zh.md](/zh/docs/components/gallery/)     # 画廊
  - image/                                             # 页面包
    - [index.zh.md](/zh/docs/components/image/)       # 图片
- [hugo.yml](https://github.com/pgsty/oink.pgsty.com/blob/main/hugo.yml)   # 站点配置（GitHub）
```

按平台分成标签页

围栏带 tab=（以及 group= value=）时成为一组标签页中的一页，可以与代码围栏混排。

```filetree {tab="Linux" group="platform" value="linux"}
- /etc/pigsty/          # 配置
- /var/lib/pgsql/       # 数据
- /usr/bin/pig          # 可执行文件
```
```filetree {tab="macOS" value="macos"}
- ~/Library/Application Support/pigsty/   # 配置
- /opt/homebrew/bin/pig                   # 可执行文件
```

输出形态

窄屏（小于 sm 断点）时布局收成单列：注释移到名称下方，不再截断，分隔条隐藏。不带注释的树是单列，也不加载任何脚本。

参数参考

围栏属性（写在 ```filetree 后面）：

条目属性（写在每行末尾的 {…} 里）：

行语法本身：

未知属性、未知取值、写在文件上的 open、格式错误的 {…}、退回到未打开过的缩进层级，都会构建失败，并给出围栏内的行号。

限制与常见问题

• 只有 filetree 围栏这一种形态：没有 {.filetree} 列表标记，也没有 shortcode。
• 注释与名字都是纯文本：写 **粗体** 会原样显示，围栏源码在任何环境里都读得通。
• 不读取磁盘：树是手写或粘贴的静态内容，不随仓库变化。
• 不提供搜索、多选、复制整棵树：需要逐字复制时用普通代码块。
• 分栏宽度不持久化：拖动过的位置刷新后回到构建期算出的默认值。

相关

• 代码块 — 需要逐字复制的清单
• 标签页 — 按平台并列多棵树
• 徽章 — tone 用的是同一套词汇
• 目录与页面组织 — 真实的内容目录该怎么排

10 - 公式

公式由 KaTeX 在构建期渲染成 HTML + MathML，页面只额外加载一份本地 KaTeX 样式表，没有 JavaScript，也不请求远程数学服务。行内公式写 \(…\)，块级公式写 $$…$$、\[…\]，另有 math 与 chem 两种围栏。需要 TikZ 绘图或 KaTeX 不支持的宏包时，改用预渲染的图片。

最简例子

行内公式写在句子中，前后的空格与标点留在分隔符外面。

共享缓冲区命中率是 \(\mathrm{hit} = \frac{H}{H + R}\)，其中 \(H\) 是 `blks_hit`，\(R\) 是 `blks_read`。

共享缓冲区命中率是 $\mathrm{hit} = \frac{H}{H + R}$，其中 $H$ 是 blks_hit，$R$ 是 blks_read。

块级公式

独占一段的公式用 $$ 包起来，居中显示，字号更大。\[…\] 是等价写法。

一棵扇出为 \(f\)、共 \(N\) 个键的 B 树，其高度为：

$$
h = \left\lceil \log_{f} N \right\rceil
$$

一棵扇出为 $f$、共 $N$ 个键的 B 树，其高度为：

一行装不下的长公式在正文列内横向滚动，不会把版面撑宽；打印时保持静态。

math 围栏

math 围栏是块级公式的另一种写法，不依赖站点的 passthrough 配置。源码在 GitHub 上是一个普通代码块。

```math
N_{\text{conn}} = \lambda \cdot \bar{t}_{\text{resp}}
```

上式是 Little 定律在连接池上的形式：稳态下需要的并发连接数等于到达速率乘以平均响应时间。连接池大小通常远小于客户端数量。

化学式与单位

chem 围栏使用 KaTeX 的 mhchem 扩展，正文写 \ce{…}。同一个扩展也能排物理单位。

```chem
\ce{CO2 + H2O <=> H2CO3 <=> H+ + HCO3^-}
```

语法见 mhchem 手册。

编号公式

块级公式下面跟一行属性即成为编号公式。num 是作者书写的字符串（3-1、5.3），主题不自动计数；#id 不写时默认为 eq-<num>。编号显示在公式右侧，前缀「公式」按站点语言本地化。

$$
\text{WAL}_{\text{day}} \approx \text{TPS} \times \bar{s}_{\text{record}} \times 86400
$$
{#eq-wal num="3-1" caption="每日 WAL 产量的估算"}

见[公式 3-1](#eq-wal)：乘上保留天数就是归档盘容量的下限。

见公式 3-1：乘上保留天数就是归档盘容量的下限。

caption（纯文本）可以省略。#id 与 caption 必须与 num 同时出现，不存在「半编号」的公式。同一页里重复的 ID、或同一编号指向两个 ID，都会构建失败。

交叉引用

正文可以用普通链接引用编号公式，上一节即是这种写法。跨页引用、或需要自动带上「公式 N」标签时用 xref：

容量规划从 {{< xref eq="3-1" anchor="eq-wal" />}} 开始。

容量规划从 公式 3-1 开始。

xref 可以写在目标之前，前向引用合法。整本书的公式目录、book-equations 索引见书籍出版。

eq shortcode

eq 供无法开启 passthrough 的站点使用，正文交给同一个 KaTeX 渲染器。不带参数时是一个不注册编号的块级公式；带 num 时与上一节的属性行形态等价。

{{< eq >}}\sigma_{\text{idx}} = \frac{\text{rows}_{\text{matched}}}{\text{rows}_{\text{total}}}{{< /eq >}}

{{< eq num="3-2" caption="顺序扫描与索引扫描的代价平衡点" >}}
c_{\text{seq}} \cdot P = c_{\text{rand}} \cdot \sigma \cdot T
{{< /eq >}}

本站已开启 passthrough，日常写作用 $$。eq 用于迁移来的书稿与不能修改 hugo.yml 的场合。

站点前置配置

math 与 chem 围栏无需配置。$$、\[…\]、\(…\) 这些分隔符依赖 Goldmark 的 passthrough 扩展。Hugo 不合并主题的 markup 配置，这段必须写在站点自己的配置文件里。本站使用下面这份：

markup:
  goldmark:
    parser:
      attribute:
        block: true # 编号公式的属性行需要它
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]

各键的完整定义见配置总览。分隔符不能与站点正文冲突：单个 $ 没有配进去，避免「$5」这样的价格被当成公式。

输出形态

任何形态都不加载 JavaScript。

参数参考

四种写法：

块级公式的属性行 {…}：

eq shortcode 的参数：

TeX 写错（未知命令、括号不配对）会构建失败，报错里带 KaTeX 的信息与源码位置。

限制与常见问题

• 分隔符由站点配置决定：$$、\[…\]、\(…\) 是否渲染只取决于站点 markup.goldmark 的 passthrough 扩展。front matter 里写 math: true 主题不读，缺少配置时 $$ 仍然原样显示；改用 math 围栏或 eq 可以绕开。
• 只有 $$ 块和 eq 能编号：math 围栏不接受属性行，需要编号就换写法。
• 编号是手写的：主题不自动计数，也不重排；调整章节顺序要自己改 num。
• 行内公式不能带属性：属性行只对块级公式有效。
• caption 是纯文本：里面的 Markdown 不解析。

相关

• 代码块 — 围栏参数与代码编号
• 图片 — 图的编号用同一套 {#id num=}
• 书籍出版 — 公式目录与跨页交叉引用
• 配置总览 — markup.goldmark 相关键

11 - Mermaid

mermaid 围栏把一段文本渲染成流程图、时序图、甘特图、类图、ER 图与状态图。图以源码形式存在，可以进 Git、可以 review diff、可以被搜索命中；渲染由主题自带的 Mermaid 在读者浏览器里完成，不请求外部服务。需要像素级控制的示意图画成 SVG，按图片使用。

最简例子

```mermaid
flowchart LR
  内容["content/"] --> Hugo
  配置["hugo.yml"] --> Hugo
  主题["OINK 主题"] --> Hugo
  Hugo --> 站点["public/"]
```

flowchart LR
  内容["content/"] --> Hugo
  配置["hugo.yml"] --> Hugo
  主题["OINK 主题"] --> Hugo
  Hugo --> 站点["public/"]

围栏语言写 mermaid 即可，没有其它开关。主题检测到这个围栏后才把 Mermaid 运行时加入这一页，同一页里画十张图也只加载一次。

时序图

sequenceDiagram 描述参与者之间按时间发生的消息，适合说明请求链路与加载顺序。

```mermaid
sequenceDiagram
  autonumber
  participant 读者 as 读者浏览器
  participant CDN as 静态托管
  participant JS as 页面脚本包
  读者->>CDN: GET /zh/docs/components/mermaid/
  CDN-->>读者: HTML（含 <pre class="mermaid">）
  读者->>CDN: GET 本页的脚本包
  CDN-->>读者: mermaid.min.js
  JS->>JS: 把围栏源码渲染成 SVG
  Note over JS: 未使用的运行时不下载
```

sequenceDiagram
  autonumber
  participant 读者 as 读者浏览器
  participant CDN as 静态托管
  participant JS as 页面脚本包
  读者->>CDN: GET /zh/docs/components/mermaid/
  CDN-->>读者: HTML（含 <pre class="mermaid">）
  读者->>CDN: GET 本页的脚本包
  CDN-->>读者: mermaid.min.js
  JS->>JS: 把围栏源码渲染成 SVG
  Note over JS: 未使用的运行时不下载

甘特图

gantt 画时间区间。下面是 PostgreSQL 各大版本从发布日算起的五年社区支持期，1825d 即五年。

```mermaid
gantt
  title PostgreSQL 大版本的五年社区支持期
  dateFormat YYYY-MM-DD
  axisFormat %Y
  section PG 15
  发布于 2022-10-13 :2022-10-13, 1825d
  section PG 16
  发布于 2023-09-14 :2023-09-14, 1825d
  section PG 17
  发布于 2024-09-26 :2024-09-26, 1825d
  section PG 18
  发布于 2025-09-25 :active, 2025-09-25, 1825d
```

gantt
  title PostgreSQL 大版本的五年社区支持期
  dateFormat YYYY-MM-DD
  axisFormat %Y
  section PG 15
  发布于 2022-10-13 :2022-10-13, 1825d
  section PG 16
  发布于 2023-09-14 :2023-09-14, 1825d
  section PG 17
  发布于 2024-09-26 :2024-09-26, 1825d
  section PG 18
  发布于 2025-09-25 :active, 2025-09-25, 1825d

类图与 ER 图

classDiagram 画类型与关系，erDiagram 画实体与基数。两者都常用来解释数据模型。

```mermaid
classDiagram
  class Page {
    +string Title
    +string Description
    +int Weight
    +Content()
    +OutputFormats()
  }
  class Resource {
    +string Name
    +string RelPermalink
    +Resize(spec)
  }
  class OutputFormat {
    +string Name
    +string MediaType
  }
  Page "1" --> "0..*" Resource : 页面包资源
  Page "1" --> "1..*" OutputFormat : html / print / markdown / rss
```

classDiagram
  class Page {
    +string Title
    +string Description
    +int Weight
    +Content()
    +OutputFormats()
  }
  class Resource {
    +string Name
    +string RelPermalink
    +Resize(spec)
  }
  class OutputFormat {
    +string Name
    +string MediaType
  }
  Page "1" --> "0..*" Resource : 页面包资源
  Page "1" --> "1..*" OutputFormat : html / print / markdown / rss

```mermaid
erDiagram
  pg_database ||--o{ pg_namespace : "包含模式"
  pg_namespace ||--o{ pg_class : "包含关系"
  pg_class ||--o{ pg_attribute : "包含列"
  pg_class ||--o{ pg_index : "被索引"
  pg_class {
    oid oid PK
    name relname
    char relkind
  }
  pg_attribute {
    oid attrelid FK
    name attname
    smallint attnum
  }
```

erDiagram
  pg_database ||--o{ pg_namespace : "包含模式"
  pg_namespace ||--o{ pg_class : "包含关系"
  pg_class ||--o{ pg_attribute : "包含列"
  pg_class ||--o{ pg_index : "被索引"
  pg_class {
    oid oid PK
    name relname
    char relkind
  }
  pg_attribute {
    oid attrelid FK
    name attname
    smallint attnum
  }

状态图

stateDiagram-v2 画状态与迁移条件。下面是 OINK 主题一次发布依次经过的五个状态。这五个状态互不等价，本地构建通过不属于其中任何一个。

```mermaid
stateDiagram-v2
  [*] --> 源码完成
  源码完成 --> 已验证 : 主题检查脚本 + 站点测试套件全绿
  已验证 --> 已发布 : 推送不可变的签名 vX.Y.Z 标签
  已发布 --> 已文档化 : 站点 go.mod 钉住该标签
  已文档化 --> 已部署 : 生产构建上线
  已部署 --> [*]
  已发布 --> 源码完成 : 发现问题只能出新补丁版本，标签不移动
```

stateDiagram-v2
  [*] --> 源码完成
  源码完成 --> 已验证 : 主题检查脚本 + 站点测试套件全绿
  已验证 --> 已发布 : 推送不可变的签名 vX.Y.Z 标签
  已发布 --> 已文档化 : 站点 go.mod 钉住该标签
  已文档化 --> 已部署 : 生产构建上线
  已部署 --> [*]
  已发布 --> 源码完成 : 发现问题只能出新补丁版本，标签不移动

单张图的标题与配置

围栏正文最前面可以写 Mermaid 自己的 YAML 头，它不是 Hugo front matter。title 给图加标题，config 覆盖这一张图的 Mermaid 配置。写死 config.theme 的图不再跟随站点深浅色。

```mermaid
---
title: 只有用到的运行时才会进包
config:
  flowchart:
    curve: linear
---
flowchart TD
  页面 --> 判断{用了什么组件？}
  判断 -->|Mermaid 围栏| M[mermaid.min.js]
  判断 -->|ECharts 围栏| E[echarts.min.js]
  判断 -->|都没用| B[只有基础包]
```