组件参考

• 1: 代码块与代码组
• 2: Badge
• 3: Kbd
• 4: Fields 与 Field
• 5: FileTree
• 6: Gallery
• 7: Image Zoom
• 8: 短代码
• 9: 图表与公式
• 10: Apache ECharts
• 11: 使用 AntV 创建信息图

1 - 代码块与代码组

OINK 在不替换 Chroma、也不引入浏览器端高亮器的前提下增强 Hugo 普通围栏代码块。服务器输出完整代码与外壳；按页面加载的小型脚本只负责复制、视觉折叠与标签状态。

增强围栏

在 Hugo 围栏属性列表中补充元数据。没有属性的围栏也会获得同一套响应式外壳与默认复制行为。filename 会增加可见标题栏；title 是它的兼容别名，同时设置两者会导致构建失败。两者都没有时，OINK 使用紧凑浮层，不绘制空标题栏。

作者写法

```yaml {filename="hugo.yml" copy="all" lineNos="table" hl_lines="4 7-9" wrap=false collapse=18}
params:
  offlineSearch: true
```

实时效果

实际效果

下面的代码块同时使用了文件名、内联行号、稳定根 ID、行链接和源码行高亮。显示的行号从 12 开始，但 hl_lines 仍按围栏内的源码行编号：

12markup:
13  highlight:
14    noClasses: false
15params:
16  offlineSearch: true
17  ui:
18    sidebar_menu_foldable: true

外壳参数

Hugo 通用 class、安全的 data-*、aria-* 与全局属性会保留在 .td-code 根元素。以 data-td-code 开头的名称和 data-language 为保留项；事件处理器与内联样式属性会被拒绝。需要覆盖由文件名派生的无障碍名称时，应使用 label；同时设置通用 aria-label 与 label 或 filename 会导致构建失败。

Hugo 选项

渲染钩子仍会把以下选项传给 Hugo：

• lineNos、lineNoStart 与 anchorLineNos；
• hl_lines；
• tabWidth 与 style。

基于 class 的 Chroma 标记仍位于 .highlight 和 .chroma 中，因此既有 token 级覆盖可以继续工作。新的稳定外层元素是 .td-code；使用 .td-content > .highlight 等直接子选择器的站点需要更新选择器。

界面会把常见的 bash、sh 与 shell lexer 别名统一显示为 BASH。传给 Chroma 的原始 lexer 值以及 data-language 不会改变。

Diff 有意继续使用 Chroma 标准的 diff lexer，不引入自定义 transformer：

作者写法

```diff {filename="hugo.yaml.diff"}
 params:
-  offlineSearch: false
+  offlineSearch: true
```

实际效果

 params:
-  offlineSearch: false
+  offlineSearch: true

复制语义

普通源码默认使用 copy="all"。console 与 shell-session 默认使用 copy="command"：只复制含 Chroma 提示符 token 的行，并排除提示符与输出 token。确实需要完整终端记录时可设置 copy="all"；在其他语言上使用 command 会导致构建失败。

复制会保留缩进、内部空行与 Unicode，移除行号，只裁掉末尾换行符并补上恰好一个最终换行。会话 lexer 没有生成提示符 token 时，界面会报告本地化失败并且不复制任何内容。设置 params.disable_click2copy_chroma: true 可以在整个站点硬关闭复制。

复制控件只显示紧凑图标，不在旁边重复文字。它仍通过无障碍名称与悬停提示提供本地化说明；成功或失败时也会切换图标并更新实时状态消息。

多行终端命令应在每个续行中写出续行提示符（通常为 >）。Chroma 会把没有提示符的行分类为输出，因此 copy="command" 会有意排除这些行。

下面这个实时会话的复制操作只会得到两条命令，不会包含提示符与输出：

作者写法

```console {title="终端会话"}
$ hugo version
hugo v0.164.0+extended darwin/arm64
$ hugo --gc --minify
Total in 742 ms
```

实际效果

$ hugo version
hugo v0.164.0+extended darwin/arm64
$ hugo --gc --minify
Total in 742 ms

换行与折叠

wrap=true 只改变显示，不会改变复制出的源码。它与 Chroma 表格行号布局不兼容，因为独立换行的行号栏和源码栏会错位；应使用内联行号或关闭换行。OINK 会让构建明确失败，而不是静默产生错位结果。

collapse=N 属于渐进增强。服务器始终输出全部源码；浏览器只有在能够测量第 N 个真实 Chroma 行节点后才会裁切。没有 JavaScript、使用辅助技术以及打印时，代码始终完整。减少动态效果偏好会关闭高度动画。

第一个示例会在视觉上换行长值，但不会改动复制出的文本：

作者写法

```text {filename="config/artifacts.env" wrap=true}
ARTIFACT_URL=https://downloads.example.com/releases/2026/08/oink-complete-offline-distribution-arm64.tar.zst
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2
```

实际效果

ARTIFACT_URL=https://downloads.example.com/releases/2026/08/oink-complete-offline-distribution-arm64.tar.zst
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2

第二个示例由服务器输出全部内容，但在浏览器中初始只显示六行：

作者写法

```yaml {filename="hugo.yaml" collapse=6}
baseURL: https://docs.example.com/
title: Product Documentation
defaultContentLanguage: en
languages:
  en:
    label: English
    weight: 1
  zh:
    label: 简体中文
    weight: 2
params:
  offlineSearch: true
```

实际效果

baseURL: https://docs.example.com/
title: Product Documentation
defaultContentLanguage: en
languages:
  en:
    label: English
    weight: 1
  zh:
    label: 简体中文
    weight: 2
params:
  offlineSearch: true

稳定 ID 与行链接

发布行号链接时应设置页面内唯一的明确 id。ID 不能包含 ASCII 空白或控制字符，也不能与其他代码组件生成的 viewport、标签、面板、标题或行锚点 ID 冲突；任何此类冲突都会导致构建失败：

作者写法

```go {id="zh-server-start" lineNos="inline" anchorLineNos=true}
func start() {}
```

实际效果

1func start() {}

OINK 会从该 ID 派生唯一行锚点前缀。自动生成的 ID 在页面内是安全的，但依赖代码块顺序，不构成永久链接契约；在前面插入新围栏可能改变它。

代码组

如果多个示例是同一任务的替代方案，应使用 code-group：

作者写法

{{< code-group id="zh-docs-install-client" sync="zh-docs-package-manager" persist=false
    label="选择包管理器" copy="all" >}}
  {{< code-tab title="npm" value="npm" lang="bash" >}}
npm install @example/client
  {{< /code-tab >}}
  {{< code-tab title="pnpm" value="pnpm" lang="bash" selected=true >}}
pnpm add @example/client
  {{< /code-tab >}}
  {{< code-tab title="yarn" value="yarn" lang="bash" >}}
yarn add @example/client
  {{< /code-tab >}}
{{< /code-group >}}

实际效果

npm install @example/client

pnpm add @example/client

yarn add @example/client

code-tab 包含原始代码而不是 Markdown。OINK 会移除用于排版的首个换行和结束短代码前的缩进，同时保留源码内部的全部空白。Markdown 格式化工具可能会重排这段原始内容；使用 Prettier 时，应像下面的实时示例一样，在每个 code-group 前紧邻放置 <!-- prettier-ignore -->。

分组与标签参数

每个分组都需要页面内唯一的小写 id。可选的 sync、persist、label、copy、wrap 和 collapse 作用于整个分组；后三项会作为子项继承的默认值。persist 默认为 true。

每个子项都需要纯文本 title 与稳定的小写 value。lang 默认为 text；selected、copy、wrap、collapse 和 Hugo 高亮选项可以覆盖分组默认值。分组不能为空、不能重复 value，也不能有多个 selected=true 子项。代码组不支持文件名，因为标签本身已经标识示例。

选择、同步与持久化

选中面板的公开 hash 是 #<group-id>-<value>，例如 #install-client-pnpm。初始选择优先级依次为 URL hash、已保存值、selected=true、第一个子项。

共享 sync 的分组会在双方都存在某个 value 时同步选择；缺少该 value 的同伴保持不变。用户选择会通过 replaceState 更新 hash，并在启用持久化时保存 value。访问分享 hash 会激活指定示例，但不会覆盖读者保存的偏好。persist=false 只关闭存储，不会关闭页面内同步。

实时同步分组

上面的安装分组与下面的运行分组共享同一个 sync key。在任意分组中选择包管理器，另一个分组都会随之切换。安装分组的 npm、pnpm 与 yarn 面板也都有可分享的 hash。

作者写法

{{< code-group id="zh-docs-run-client" sync="zh-docs-package-manager" persist=false >}}
  {{< code-tab title="npm" value="npm" lang="bash" >}}
npm run docs:dev
  {{< /code-tab >}}
  {{< code-tab title="pnpm" value="pnpm" lang="bash" selected=true >}}
pnpm docs:dev
  {{< /code-tab >}}
  {{< code-tab title="yarn" value="yarn" lang="bash" >}}
yarn docs:dev
  {{< /code-tab >}}
{{< /code-group >}}

实际效果

npm run docs:dev

pnpm docs:dev

yarn docs:dev

输出与兼容性

打印会隐藏控件与标签行、展开全部代码，并在每个分组示例前显示标题。Markdown 输出会把代码组与旧标签分别还原为可读的带标题围栏；源码包含反引号时会自动选择更长的围栏。Feed 与其他非交互输出使用顺序堆叠示例。没有相关代码或标签的页面不会加载对应 runtime。

既有 tabpane 源码及其 td-tp-persist:* 浏览器键保持兼容。Prism 仍是旧版替代方案，不会获得 Enhanced Code Block 或 Code Group。mermaid、math、chem、markmap 与 plantuml 等专用钩子继续使用各自渲染器。

2 - Badge

Badge 用于在功能、选项或版本名称旁边放置简短状态。作者选择语义 tone，Oink 再把它映射到主题 token，确保浅色与深色模式下都有足够的对比度。

适用场景

Badge 适合 Beta、New、Experimental 与 Deprecated 等生命周期状态。标签文字必须明确：颜色只能补充含义，不能代替文字。如果状态需要解释、操作说明或截止日期，请改用普通正文或提示框。

快速开始

源码

{{< badge text="Beta" tone="warning" >}}
{{< badge text="已弃用" tone="danger" outline=false >}}
{{< badge text="v0.3" tone="info" link="/zh/blog/release/" >}}

渲染结果

默认 信息 已支持 Beta 已弃用 v0.3

最后一个 Badge 是链接，其余都是静态行内标签。

参数

布尔值不能加引号。例如应写作 outline=false，而不是 outline="false"。未知参数、非法 tone 或非法链接都会让 Hugo 构建停止，并报告源文件位置。

语义与回退

静态 Badge 输出为 span，带链接的 Badge 输出为 a。Oink 不会把它变成实时状态区域，因此新增 Badge 不会触发意外的屏幕阅读器播报。所有输出都保留可见文字：Markdown 使用强调文本并保留链接，打印与 RSS 使用静态行内内容。Badge 不加载 JavaScript。

有意保留的边界

Badge 不接受任意颜色、CSS class、样式或事件处理器。第一版也不提供 icon 参数。目前请使用简短而明确的文字；内容图标应在名称、许可证、无障碍与 Markdown 回退契约确定后，再单独提供公共接口。

3 - Kbd

Kbd 用于把实际按键和快捷键与周围正文区分开。它输出语义化 HTML，在 Markdown 与打印中仍然清晰，而且不需要 JavaScript。

适用场景

Kbd 适合读者需要按下的按键，包括多键快捷键。命令、选项名或读者需要输入的文本应使用行内代码，因为它们并不是物理或虚拟按键。

快速开始

源码

按 {{< kbd "Ctrl" "K" >}} 打开搜索。
按 {{< kbd "⌘" "Shift" "P" >}} 打开命令面板。

渲染结果

按 Ctrl+ 加 K 打开搜索。按 ⌘+ 加 Shift+ 加 P 打开命令面板，或按 Alt+ 加 Enter 应用操作。

接口

Kbd 接受一个或多个非空位置字符串：

{{< kbd "按键" >}}
{{< kbd "第一个按键" "第二个按键" "第三个按键" >}}

它不接受命名参数。每个按键都必须是字符串，因此需要使用引号。缺少按键、空字符串、命名参数或非字符串值都会让构建停止，并报告源文件位置。

平台差异有意义时，请使用对应平台键盘上印刷的标签。跨平台说明应在正文中写明平台，不要把多个备选值塞进同一个按键序列。

语义与回退

HTML 为每个按键输出一个嵌套的 kbd 元素。视觉上的加号会对辅助技术隐藏，屏幕阅读器则使用本地化连接词分隔按键。Markdown、打印与 RSS 使用 Ctrl + K 这样的明确序列。即使没有 CSS 或 JavaScript，操作说明仍然完整。

有意保留的边界

Kbd 只表示同时按下的按键序列，不负责菜单、手势输入、按键映射、平台检测或交互式快捷键录制器。连续操作请直接写在正文中，例如“先按 Escape，再按 Enter”。

4 - Fields 与 Field

fields 与 field 子项用于记录具名值及其元数据。组件使用响应式定义列表，而不是固定宽度的大表格，因此长名称和长描述在窄屏上仍然可用。

适用场景

Fields 适合配置键、命令或 API 参数、对象属性与响应字段。如果读者需要按相同列横向比较大量条目，请使用普通 Markdown 表格；如果条目表达的是步骤而不是定义，请使用正文。

快速开始

源码

{{< fields label="搜索配置" >}}
  {{< field name="offlineSearch" type="boolean" required=true default=true >}}
  构建 **本地** 搜索索引与命令面板。
  {{< /field >}}

  {{< field name="offlineSearchMaxResults" type="integer" default=10 >}}
  限制可见结果数量。
  {{< /field >}}
{{< /fields >}}

渲染结果

描述可以使用 Markdown，包括链接、强调、行内代码与列表。每段描述应保持独立完整，因为 Markdown 输出会把它放在对应元数据下方。

Fields 参数

容器至少要有一个直接 field 子项。直接放在 fields 中的普通文字或其他短代码会让构建停止。

Field 参数

每个 field 还必须包含非空正文，并且必须是 fields 的直接子项。参数名称与类型在构建时校验，未知参数会被视为错误。

语义与回退

HTML 使用 dl、dt 与 dd。每个条目上下两行：第一行是字段名，随后依次是 type、required 与 default 标记，描述在下一行；条目之间以细分隔线分隔。required 与 default 标记在所有语言下都保持英文原文。可选标签会为辅助技术命名整个定义列表。Markdown 输出为带缩进的项目列表，名称、类型与默认值使用代码格式；打印与 RSS 保留所有定义。组件不会加载 JavaScript。

有意保留的边界

第一版不实现 kind、deprecated、since、location 或字段级链接，也不会在 Hugo 内解析 TypeScript 或 API schema。将来可以由外部生成器输出这些短代码，把编译器与 schema 运行时留在主题之外，同时保持当前输出契约。

5 - FileTree

FileTree 用于解释仓库或目录结构中与读者有关的部分。交互式 HTML 使用原生展开控件表示目录，所有输出格式都会保留完整嵌套结构。

适用场景

FileTree 适合安装指南、架构概览与贡献说明中的精选结构。如果需要逐字复制命令输出，请使用代码块。对于自动生成或频繁变化的目录树，应使用正文描述，不要提交很快就会过时的大型快照。

快速开始

源码

{{< filetree label="仓库结构" >}}
  {{< filetree/folder name="content" open=true >}}
    {{< filetree/file name="_index.md" >}}
    {{< filetree/folder name="docs" open=true >}}
      {{< filetree/file name="getting-started.md" >}}
    {{< /filetree/folder >}}
  {{< /filetree/folder >}}
  {{< filetree/file name="hugo.yml" link="/zh/docs/getting-started/" >}}
{{< /filetree >}}

渲染结果

blog 目录初始为关闭状态。使用指针、Enter 或 Space 操作摘要即可显示子文件；这项行为来自原生 details 元素，不依赖自定义脚本。

根组件参数

根组件只接受直接的 filetree/folder 与 filetree/file 子项。不要发布空树，应至少添加一个有意义的条目。

目录与文件参数

目录可以递归包含目录与文件，文件不能包含子项。未知参数、子项之间的普通文字，或放在非法父级中的子项都会让构建停止，并报告源文件位置。

语义与回退

整体结构是嵌套 ul，交互式目录添加原生 details 与 summary。Oink有意不声明 role="tree"，因为这种 ARIA 控件需要实现完整的方向键导航模型。打印与 RSS 会展开所有目录，Markdown 会变成嵌套列表，并在适用时保留文件链接。组件不会加载 JavaScript。

有意保留的边界

FileTree 完全由作者控制，绝不会在 Hugo 构建期间读取本地目录，因此构建安全且可复现。第一版也不为条目提供公共 badge 或 icon 参数；内置目录与文件图形只是主题的展示细节，不属于内容 API。

6 - Gallery

Gallery 使用响应式网格组织相关图片。它以静态内容为基础：没有 JavaScript 时，图片、替代文字与说明文字仍然完整。启用 Image Zoom 后，Gallery 会复用同一个对话框，而不会加载另一套灯箱。

适用场景

Gallery 适合比较少量截图、状态或相关视觉示例。如果顺序和对比不重要，请使用单张图片。如果内容确实需要幻灯片导航，而且隐藏非当前条目可以接受，请使用 Carousel。

快速开始

源码

{{< gallery columns=3 label="OINK 截图" >}}
  {{< gallery/image
    src="images/content-primitives/oink.webp"
    alt="OINK 文档概览"
    caption="文档概览"
  >}}
  {{< gallery/image
    src="/images/feedback.png"
    alt="OINK 反馈界面"
    caption="反馈控件"
  >}}
{{< /gallery >}}

渲染结果

本页启用了 Image Zoom。操作任意图片即可在共享对话框中查看。禁用 JavaScript 时，同样三张 figure 仍会按照相同阅读顺序显示。

Gallery 参数

容器至少需要一个直接 gallery/image 子项，不能包含普通正文。小视口会减少实际列数，但不会改变作者要求的桌面端最大值。

Image 参数

对于本地 Hugo 资源，Gallery 会在能够确定时记录固有宽高，并添加 lazy loading。它接受远程来源 URL，但绝不会在 Hugo 构建期间下载该图片，因此无法获得远程尺寸。Caption 不渲染 Markdown；请保持简短，把复杂说明放在相邻正文中。

语义与回退

HTML 使用带标签的 ul，其中包含 figure、img 与可选 figcaption。每张图片保留自己的替代文字，Gallery 标签为整个集合命名。Markdown 输出普通图片，后面接斜体说明；打印与 RSS 输出连续的静态 figure。Gallery 没有私有 JavaScript 运行时，只会在页面级 Image Zoom 启用时标记图片。

有意保留的边界

Gallery 不会把图片裁剪为强制宽高比，不会按断点重新排序，也不会隐藏溢出或提供幻灯片导航。它没有 Gallery 专用灯箱。这些约束保留了文档顺序，并确保回退内容完整。

7 - Image Zoom

Image Zoom 使用一个原生对话框渐进增强符合条件的内容图片。对于在正文宽度下难以看清细节的截图与架构图，它尤其有用。没有 JavaScript 或对话框支持时，原图片仍然完整可读。

适用场景

当读者确实需要放大查看原图时再启用 Zoom。如果放大仍然不能解决可读性问题，应提供专门裁剪的图片或更清晰的图表。装饰图标、正文中的小型 Logo 与带链接缩略图应保留原有行为。

启用功能

Image Zoom 默认关闭。在 Hugo 配置中为全站启用：

params:
  ui:
    image_zoom:
      enable: true

页面可以在 front matter 中使用相同结构覆盖全站值。必须使用真正的布尔值：

params:
  ui:
    image_zoom:
      enable: false

只有启用该功能并且存在合格图片的页面，Oink 才会加入 JavaScript 运行时与对话框。仅打开开关不会给纯文本页面增加运行时。

快速开始

源码

普通的独立 Markdown 图片符合条件。如果希望 Oink 生成较小预览，同时打开原始图片，可以使用命名形式的 imgproc：

{{< imgproc
  src="images/content-primitives/oink.webp"
  command="Fit"
  options="640x320"
  alt="OINK 本地优先文档预览"
>}}
经过处理的预览，说明文字支持 **Markdown**。
{{< /imgproc >}}

渲染结果

使用指针、Enter 或 Space 打开图片。按 Escape、可见关闭按钮或点击背景即可关闭对话框。

链接中的图片会被有意跳过，并继续作为链接工作：

合格图片

图片必须同时满足以下条件，Oink 才会增强：

• 图片独立位于段落或 figure 中，或者由 Gallery 显式标记。
• 图片具有非空 alt 值和可用来源。
• 图片不在链接、按钮或标记了 data-no-zoom 的元素中。
• 图片没有设置 aria-hidden="true"、role="presentation" 或 role="none"。

夹在文字中的行内图片与空 alt 装饰图片会被跳过。在受信任的 HTML 中，如果某张原本符合条件的图片不应打开，作者可以为图片或其祖先添加 data-no-zoom。

命名 imgproc 参数

可选的短代码正文是 Markdown 说明文字。历史三值位置参数形式的 imgproc 继续兼容，但新内容应使用命名形式，以便在构建时强制检查替代文字。

交互与回退

渐进增强会把合格图片包装在带有 aria-haspopup="dialog" 的真实按钮中。原生对话框把焦点移到关闭按钮，支持 Escape，复制图片的替代文字与直接说明文字，并在关闭后恢复焦点。没有 JavaScript 或 HTMLDialogElement 时，图片与说明仍是普通静态内容。Markdown、打印与 RSS 不包含对话框控件。

有意保留的边界

第一版不实现拖拽、平移、滚轮缩放、编辑或上一张/下一张导航，也绝不会在构建期间下载远程图片。需要组织相关图片时，请使用 Gallery，并复用同一个对话框。

8 - 短代码

短代码用于表达普通 Markdown 无法承载的行为。OINK 保留 Docsy 核心组件，并新增本地提供的图表、终端录像、信息图、轮播、卡片和折叠组件。浏览器运行时只在实际使用它们的页面加载。

标题、正文、列表、链接、表格和图片应优先使用 Markdown。短代码一旦投入使用，就成为内容 API 的一部分：修改名称或参数可能破坏所有调用它的页面。

短代码分隔符

Hugo 支持两种形式：

• {{< name >}} 使用标准分隔符，原样传递内部内容；
• {{% name %}} 使用 Markdown 分隔符，在周围内容的上下文中渲染内部 Markdown。

请采用各组件文档指定的形式。嵌套、缩进和空行都会影响结果，在列表和块引用中尤其如此。示例里的 /* ... */ 转义用于防止 Hugo 执行正在展示的短代码。

blocks/* 短代码

块短代码用于组合全宽落地页。color 参数使用 OINK/Bootstrap 语义颜色或项目自定义块样式，height 参数接受各组件说明的取值。

blocks/cover

使用页面包中匹配 *background* 的图片以及可选的 *logo* 创建首屏：

{{< blocks/cover title="OINK" subtitle="本地优先文档"
    color="dark" height="max" >}} [开始使用](/zh/docs/tutorial/){ .btn .btn-lg
.btn-primary } {{< /blocks/cover >}}

image_anchor 和 logo_anchor 控制图片裁切位置，byline 用于标注图片来源。高度可取 auto、min、med、max 或 full。即使背景无法显示，首屏关键信息也必须保持可读。

blocks/lead

创建醒目的介绍区块：

{{% blocks/lead color="primary" height="min" %}} OINK 只用 Hugo
Extended 即可构建完整文档体验。 {{% /blocks/lead %}}

高度支持 auto、min、med、max 或 full。

blocks/section

创建通用落地页区块：

{{% blocks/section color="light" type="row" height="auto" %}}

### 一个分区

区块内部使用普通 Markdown。 {{% /blocks/section %}}

type 选择容器形式，height 使用块高度取值。标题级别必须与页面大纲保持一致。

blocks/feature

创建单个功能单元，通常放在 Section 中：

{{% blocks/feature icon="fa-solid fa-box-archive"
    title="离线可用" url="/zh/docs/about/local-first/"
    url_text="阅读设计说明" %}} 所需浏览器资源均已锁定版本并从本地提供。
{{% /blocks/feature %}}

图标只是装饰，含义必须由 title 和链接文本表达。

blocks/link-down

从当前块添加指向下一块的链接。它必须嵌套在块内。生成目标必须长期稳定时，应显式设置 id。

导航栏下方布局校正

直接位于固定导航下方的块使用 td-below-navbar/td-anchor-no-extra-offset 校正导航栏高度。不要自行添加任意上边距；修改导航栏尺寸后，应验证直接访问片段链接的效果。

辅助短代码

alert

旧版告警短代码仍可使用：

{{% alert title="兼容性说明" color="warning" %}}
新内容优先使用 Markdown 块引用告警。 {{% /alert %}}

color 映射到 Bootstrap 告警后缀。新内容通常应采用添加内容介绍的 Markdown 告警语法。

告警、缩进与示例

开始和结束短代码应与外层列表或块引用对齐，块级 Markdown 前后应保留空行。需要原样展示短代码时，应转义分隔符，不要把活动调用包在另一个组件中。

pageinfo

在 Markdown 外渲染信息面板：

{{% pageinfo color="info" %}} 本页介绍预览接口。 {{% /pageinfo %}}

警告信息应使用语义告警；pageinfo 适合提供页面上下文。

imgproc

处理当前页面包中的图片：

{{% imgproc "architecture" Fit "960x540" %}} OINK 运行时架构。
{{% /imgproc %}}

命令可取 Fit、Resize、Fill 和 Crop，第三个参数遵循 Hugo 图片处理语法。内部文字会成为图注；资源存在 params.byline 时会附加署名。始终提供有意义的替代文字或相邻说明。

swaggerui

嵌入本地纳管的 Swagger UI 运行时：

{{< swaggerui src="/openapi.yaml" >}}

离线或严格 CSP 部署应使用同源规范。远程 src 是显式网络依赖，也可能向该主机暴露读者元数据。当前兼容短代码在一页中只应放置一个 Swagger UI 实例。

redoc

嵌入本地纳管的 Redoc 运行时：

{{< redoc "openapi.yaml" >}}

第一个参数可以是页面相对、站点相对或显式 HTTP 规范；可选第二个参数包含 Redoc 元素选项。规范内容必须经过审查，大型 Schema 还应测试移动端表现。

iframe

嵌入另一个页面：

{{< iframe src="/demo/" name="demo" id="demo-frame"
    sandbox="allow-scripts allow-same-origin" >}}

请设置有描述力的 name、唯一的 id、后备 sub 提示，以及满足需求的最严格 sandbox。默认值支持宽度和自动高度，但跨域文档并不总能测量。iframe 是安全与隐私边界，不是通用布局工具。

OINK 内容组件

以下组件由 OINK 新增。各运行时都在 VENDOR.json 中锁定版本，并按需从同源加载。

details

创建无障碍折叠内容：

{{% details title="显示迁移说明" closed="false" %}} 正文支持 Markdown。
{{% /details %}}

closed 默认为 true。摘要应简洁，而且不得把强制操作隐藏在默认关闭的折叠区中。

steps

steps 通过自动生成的序号和垂直引导线展示连续步骤。在短代码中直接编写普通 Markdown 标题和正文，不需要手工填写数字。

请使用 Markdown 短代码分隔符，让 Hugo 渲染内部内容：

{{% steps %}}

### 创建内容

添加第一条说明。

### 检查顺序

添加下一条说明，序号会自动生成。

#### 可选细节 {class="no-step-marker"}

这个标题属于当前步骤，不会占用序号。

### 发布结果

添加最后一条说明。

{{% /steps %}}

h2 至 h6 级别的每个直接子标题都会成为一步。如果直接子标题只是当前步骤的子分区，请添加 class="no-step-marker"。同级步骤应使用相同的标题级别，并保持页面大纲合理；不要在一个 steps 块中嵌套另一个 steps 块。

asciinema

播放 asciinema .cast 录像：

{{< asciinema file="casts/install.cast" speed="1.25"
    markers="0:开始,18:验证" fit="width" >}}

窗口标题优先使用 title，没有 title 时显示 file。其他主要参数包括 theme、autoplay、loop、preload、speed、startAt、poster、cols、 rows、idleTimeLimit、pauseOnMarkers、markers 和 fit（width、height、both 或 none）。本地录像可以来自 Hugo assets 或站点相对 URL。不要自动播放，必须清除终端历史中的机密，并为关键步骤提供相邻文字说明。

echarts

Apache ECharts 是完整的可视化系统，无法用一个段落说明清楚。高级特性指南会完整介绍包装层、结构化选项、主题、响应式行为、无障碍与可信回调边界：

• ECharts 快速开始
• 声明式图表示例集
• 回调与可信代码

短代码正文接受 JSON 或 YAML 选项对象。height、theme 与 full 只能按照专门指南中的说明使用。

infographic

AntV Infographic 也有独立的高级特性指南，因为模板选择、DSL 结构、主题、视觉语义与无障碍都需要比行内示例更完整的解释：

• 信息图快速开始
• 流程、时间线与循环
• 布局、漏斗与主题

短代码正文使用 Infographic DSL。请按照专门指南使用 height 与 full，并为所有关键可视化提供含义等价的相邻文字说明。

doc-cards 与 nav-cards

两个容器都接受 1 至 4 的 cols。子卡片接受 title、link、image、alt、icon、desc、accent 与 badge：

{{< nav-cards cols="2" >}}
{{< nav-card title="开始使用" link="/zh/docs/tutorial/"
      icon="fa-solid fa-rocket" desc="使用 Hugo {version} 构建。" >}} {{< nav-card title="架构" link="/zh/docs/about/architecture/"
      badge="设计" >}}
{{< /nav-cards >}}

doc-card/doc-cards 与其共享渲染契约，适合编辑型内容；nav-card/nav-cards 则明确表示导航。{version} 等描述占位符会从站点参数解析。卡片图片采用延迟加载；除非图片纯属装饰，否则必须提供有意义的 alt。

doc-carousel

把 doc-card 放入支持键盘滚动的轮播：

{{< doc-carousel label="发布亮点" >}}
{{< doc-card title="本地资源" >}}无需 CDN。{{< /doc-card >}}
{{< doc-card title="中英双语" >}}稳定的中英文路由。{{< /doc-card >}}
{{< /doc-carousel >}}

label 为辅助技术命名该区域。上一项/下一项按钮会本地化。信息不能只存在于屏幕外卡片中；禁用脚本后，轨道仍应可用。

param

输出页面参数；根据 Hugo 的 Page.Param 规则，在页面缺省时回退到站点配置：

OINK 版本 {{< param version >}}。

找不到参数会令构建失败。param 适合显示标量值，不应用于注入未经审查的 HTML。内部兼容短代码 _param 还会为旧内容执行带编号的占位符替换。

标签页

标签页用于组织 YAML/TOML/JSON 配置等同一信息的等价表示，不应隐藏连续步骤或互不相关的选择。

{{< tabpane text=true persist=lang >}}
{{< tab header="YAML" lang="yaml" >}} params: offlineSearch: true
{{< /tab >}} {{< tab header="TOML" lang="toml" >}} [params]
offlineSearch = true {{< /tab >}} {{< /tabpane >}}

选择状态保存在浏览器本地。persist 接受 header、lang 或 disabled。已弃用的 persistLang 不应出现在新内容中。

短代码细节

text=true 将内部内容渲染为正文而不是高亮代码；right=true 把标签对齐到末端；langEqualsHeader=true 根据标题推导语言标识。父级默认值可以由单个标签覆盖。

tabpane

父组件会校验布尔值和持久化参数、生成唯一 ID，并确保存在选中项。只有禁用的标题标签确实能提供有用分组信息时才使用它。

tab

tab 必须放在 tabpane 内部。它接受 header、selected、lang、highlight、text、right 和 disabled。只能选中一个标签。面向读者的标题需要翻译，语言标识则必须稳定。

代码组

只包含代码的替代方案如果需要稳定公开 hash、同步 value 与精确复制行为，应使用 code-group/code-tab。与旧 tabpane 不同，每个子项都必须提供机器可读的 value，非交互输出则会展开所有示例。完整参数与持久化契约参见代码块与代码组。

卡片面板

旧版 cardpane/card 组合用于布局 Bootstrap 风格卡片。新的导航表面应优先使用 OINK 内容卡片，既有 Docsy 内容可以继续使用兼容组件。

card 短代码：文本内容

{{% cardpane %}}
{{% card header="说明" title="本地构建" footer="已验证" %}} Markdown
**正文**。 {{% /card %}} {{% /cardpane %}}

header、title、subtitle 和 footer 接受渲染文本。并列卡片应保持简洁，不能用卡片取代标题结构。

card 短代码：程序代码

设置 code=true，并按需设置 lang/highlight：

{{< cardpane >}} {{< card code=true header="Go" lang="go" >}}
fmt.Println("OINK") {{< /card >}} {{< /cardpane >}}

卡片组

cardpane 中相邻的卡片会形成响应式分组。应测试文字长度不一、移动端堆叠、代码溢出以及两种语言版本。

引入外部文件

readfile 短代码在构建期读取仓库文件，并将其渲染为 Markdown 或高亮代码。除非路径以 / 开头，否则路径相对于当前内容文件。

复用文档

{{% readfile "includes/installation.md" %}}

被引入的 Markdown 不是独立发布页面，因此不参加页面配对审计。如果共享正文面向读者，应有意识地创建并选择语言专属的 include 文件；Hugo 不会自动翻译 include。

安装

可复用片段应放在调用方附近的 includes/ 目录中。需要明确其所有权，并避免多层嵌套：读者和审阅者应能迅速找到源文件。

引入代码文件

{{< readfile file="includes/config.yaml" code="true" lang="yaml" >}}

code=true 会用 lang 高亮文件。绝不能引入机密、生成的凭据或不可信路径。

错误报告

找不到文件时构建会失败。draft=true 会把失败改为可见的草稿警告，只适合创作阶段，绝不能进入正式发布构建。

条件文本

conditional-text 根据 params.buildCondition 选择内容：

{{% conditional-text include-if="enterprise,preview" %}}
这段文字只出现在匹配的构建中。 {{% /conditional-text %}}

include-if 与 exclude-if 接受条件列表，同一条件不能同时出现在二者中。该功能适用于确实不同的发布变体，不应用来选择语言；多语言内容必须写入翻译后的页面文件。

9 - 图表与公式

OINK 支持 KaTeX、Mermaid、Markmap、PlantUML 和 Diagrams.net。KaTeX、Mermaid 与 Markmap 使用构建期能力或主题随附的同源资源。PlantUML 和 Diagrams.net 编辑器需要显式配置服务端点；主题不会静默使用公共服务。

使用 KaTeX 支持 LaTeX

KaTeX 可以在 Web 上渲染 TeX 数学公式。Hugo 内置的 KaTeX 支持可以在构建期间渲染公式，因此读者不需要连接远程数学服务。

行内公式

行内公式使用 Goldmark 中配置的 passthrough 分隔符。条件允许时，应把公式前后的空格与标点留在公式之外。

独立显示公式

使用 math 代码块独立显示公式：

```math
E = mc^2
```

启用 KaTeX 支持

math 与 chem 代码块会自动使用主题渲染钩子。对于行内公式和使用分隔符的公式，请启用 Goldmark 的 passthrough 扩展，并设置适合站点的分隔符。随仓库提供的 oink.pgsty.com 配置展示了方括号、双美元符号和圆括号分隔符。

启用 passthrough 扩展

相关 YAML 结构如下：

markup:
  goldmark:
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: []
          inline: []

请根据 Hugo 文档填写分隔符数组。所选分隔符不能与站点正文或代码冲突，并且必须在所有构建环境中保持一致。

添加 passthrough 渲染钩子

对于使用分隔符的数学公式，请在站点中创建 layouts/_markup/render-passthrough.html：

{{ partial "scripts/math.html" . }}

也可以把钩子放在对应布局目录下，将其限制到某种内容类型或某个分区。限制作用域可以避免把无关内容当作数学 passthrough 处理。

化学方程式与物理单位

Hugo 内置 KaTeX 支持 mhchem 扩展。化学方程式可以使用 chem 代码块；同一扩展也支持物理单位。方程式与单位语法请参阅 mhchem 手册。

使用 Mermaid 绘图

Mermaid 可以在浏览器中把文本定义转换为图表。使用 mermaid 代码块：

```mermaid
flowchart LR
  源码 --> Hugo --> 静态文件
```

flowchart LR
  源码 --> Hugo --> 静态文件

主题会检测代码块、发布固定版本的本地 Mermaid 运行时，并且在该页只加载一次。不使用 Mermaid 的页面不会加载运行时。

站点级 Mermaid 设置位于 params.mermaid：

params:
  mermaid:
    theme: neutral
    flowchart:
      diagramPadding: 6

每幅图也可以通过 Mermaid 支持的 front matter 覆盖设置。图表源码应保持可读，并同时测试深浅色模式。对于图表无法渲染时仍必须传达的信息，请提供相邻正文。

使用 PlantUML 绘制 UML 图

PlantUML 支持时序图、用例图、类图、状态图和其他面向 UML 的图表。plantuml 代码块包含图表源码：

```plantuml
actor Reader
participant Browser
participant "PlantUML endpoint" as Server
Reader -> Browser: Open page
Browser -> Server: Request encoded diagram
Server --> Browser: SVG
```

PlantUML 需要渲染端点。只有在配置了获准使用的本地或显式远程服务后才应启用：

params:
  plantuml:
    enable: true
    theme: default
    svg_image_url: https://plantuml.internal.example/plantuml/svg/
    svg: false

浏览器会把编码后的图表源码发送给端点。请评审其保密性、可用性、CSP 与离线影响。网络隔离站点应使用内部端点或提交预渲染图片，默认配置不能指向公共演示服务器。

使用 Markmap 支持思维导图

Markmap 可以把 Markdown 大纲转换为交互式思维导图：

```markmap
# 本地优先
## 构建
- Hugo Extended
## 浏览器
- 本地脚本
- 本地字体
```

# 本地优先
## 构建
- Hugo Extended
## 浏览器
- 本地脚本
- 本地字体

需要时可以全局启用：

params:
  markmap:
    enable: true

运行时采用固定版本并从本地提供。底层大纲本身也应有用，同时不要依赖只能通过指针完成的交互。

使用 Diagrams.net 绘图

Diagrams.net（draw.io）可以导出包含可编辑图表副本的 SVG 与 PNG。显式配置编辑器端点后，OINK 可以检测这些图片并显示 编辑 操作。

params:
  drawio:
    enable: true
    drawio_server: https://drawio.internal.example/

导出时请启用 Include a copy of my diagram。页面可以离线显示导出图片，但打开编辑器需要连接配置的服务。编辑器保存时会把更新后的文件下载到浏览器，不会直接写入文档仓库。

公共 Diagrams.net 端点属于在线集成。如果编辑过程必须留在组织内部，请部署获准使用的自托管编辑器，并让 drawio_server 指向它。

资源与创作检查清单

• 当可评审 diff 很重要时，优先使用文本图表。
• 为关键信息提供替代文字或相邻正文。
• 测试深浅色、移动端、打印和减少动态效果模式。
• 在 VENDOR.json 中固定本地运行时，并且只在使用时加载。
• 绝不能把机密写入会发送给服务端点的图表源码。
• 无法接受在线渲染器时，使用预渲染输出。
• 在子路径 baseURL 下验证所有资源与端点 URL。

10 - Apache ECharts

echarts 短代码使用 Oink 随主题分发的固定版本 Apache ECharts 运行时渲染选项对象。Hugo 在构建阶段解析 JSON 或 YAML，把结果序列化到页面中，并且只在实际使用该组件的页面加载 ECharts。

当定量图表需要精确控制坐标轴、视觉编码、提示或序列时，请使用 ECharts。图表旁边仍要提供文字摘要，不能让结论依赖颜色、指针交互或 JavaScript。

快速开始

{{< echarts height="300px" >}}
xAxis:
  type: category
  data: [草稿, 评审, 发布]
yAxis:
  type: value
series:
  - type: bar
    data: [12, 9, 4]
{{< /echarts >}}

这个示例表示有 12 页草稿、9 页正在评审，另有 4 页可以发布。

Oink 如何加载图表

短代码会创建唯一的图表容器，并把解析后的选项保存到 application/json 元素中。即使同一页包含多个图表，页面也只会加入一次本地 ECharts 运行时与 Oink 初始化脚本。

未设置 theme 时，Oink 会按照站点当前配色模式初始化图表，并在读者切换模式时重新绘制。ResizeObserver 会让图表随容器缩放。显式指定 ECharts 主题后，该图表不再自动跟随站点配色模式。

短代码参数

无效高度会让 Hugo 构建失败。短代码正文必须能够解析成 ECharts 选项对象；格式错误的 JSON 或 YAML 同样会在构建期报错，而不是静默生成空白图表。

选择指南

• 回调与可信代码：解释格式化函数、数据驱动样式、$fn:name 桥接方式及其安全边界。

请先使用声明式 JSON 或 YAML；只有 ECharts 选项无法用数据表达时，才添加 JavaScript 回调。

创作检查清单

• 在正文中说明图表结论与数据范围；
• 明确标注坐标轴、单位、序列与时间范围；
• 不要只依靠颜色区分重要数值；
• 在站点深浅两种配色模式中检查图例与提示；
• 使用窄屏和较长译文标签测试图表；
• 多个序列共用记录时，优先使用共享 dataset；
• 非演示数据应注明来源与观察日期；
• 动画无助于理解时不要启用，自定义效果还应尊重减少动态效果偏好。

延伸参考

OINK 负责记录包装层与交付行为，完整选项 Schema 则以 Apache ECharts 为准。图表专用配置请查阅 ECharts 概念手册、 数据集指南与 选项参考。主题发行版随附的准确运行时版本与许可证记录在 VENDOR.json 中。

11 - 使用 AntV 创建信息图

infographic 短代码使用 Oink 随主题分发的固定版本 AntV Infographic 运行时渲染 DSL。它适合展示流程、时间线、循环、漏斗、路线图与紧凑信息摘要；如果统计图显得过于生硬，可以选择信息图。

DSL 会作为数据序列化，不会作为任意 HTML 或可执行代码插入页面。浏览器运行时把它转换成 SVG，并且只在实际使用该短代码的页面加载。

快速开始

{{< infographic >}}
infographic list-row-simple-horizontal-arrow
data
  title 文档工作流
  items
    - label 草稿
      desc 写出第一个版本
    - label 评审
      desc 检查事实与语言
    - label 发布
      desc 构建并验证站点
{{< /infographic >}}

下图展示同样的三个步骤：草稿阶段写出初版，评审阶段核对事实与语言，发布阶段则构建并验证站点。

语法结构

信息图通常包含：

1. infographic TEMPLATE：选择内置 AntV 模板；
2. data 块：包含可选的 title 与 desc；
3. items 列表：包含 label、desc，以及可选的 value 和嵌套 children；
4. 可选的 theme 块：选择内置主题或显式颜色。

缩进决定结构。标签应保持简短，描述用于补充上下文；模板表达的视觉关系必须与正文一致。装饰性的序列不能替代真实的层级或对比关系。

短代码参数

无效高度与空 DSL 正文会让 Hugo 构建失败。DSL Schema 或模板错误则由浏览器运行时显示在信息图容器中。

AntV 主题属于 DSL，而不是短代码参数。它不会自动跟随 Oink 站点配色模式，因此必须在深浅两种模式中检查前景、背景与页面周围区域的对比度。

选择指南

• 流程、时间线与循环：演示三种常见的顺序说明方式；
• 布局、漏斗与主题：演示网格、逐步收窄的阶段、模板选择与内置手绘主题。

AntV 包含大量模板。请优先选择足以解释关系的最小视觉形式，不要只追求最具装饰性的模板。

创作与无障碍

• 在图形前后使用普通正文概括同一结论；
• 保持阅读顺序有意义，并缩短标签；
• 不要只通过颜色或形状传递状态；
• 检查长译文标签、窄屏、打印与站点深浅两种配色模式；
• 本地优先页面应避免远程图片或图标标识；确需使用时，必须显式审查网络与许可证边界；
• 非演示数值应注明来源与日期。

SVG 可以提高视觉保真度，但不能保证每种模板都能提供与原生标题、列表、表格相同的语义结构。关键指令必须继续出现在相邻正文中。

延伸参考

OINK 负责记录短代码与交付边界。完整 DSL、模板图库与主题模型请查阅 AntV Infographic 文档、 图库与 源码仓库。Oink 主题的 VENDOR.json 记录随附版本、校验值与 MIT 许可证文件。