组件 on OINK

代码块与代码组

Mon, 01 Jan 0001 00:00:00 +0000

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

外壳参数

属性	取值	行为
`filename`	字符串	可见文件名与无障碍分组名称
`title`	字符串	普通围栏中 `filename` 的别名
`copy`	`all`、`command`、`false` 或 `true`	复制策略；`true` 等价于 `all`
`wrap`	`true` 或 `false`	仅在视觉上换行，不改变源码
`collapse`	正整数	初始最多显示的源码行数
`label`	字符串	文件名不适用时的无障碍标签
`id`	字符串	稳定公开块 ID 与行锚点前缀

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

Badge

Mon, 01 Jan 0001 00:00:00 +0000

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

适用场景

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

快速开始

源码

GO-HTML-TEMPLATE

{{< 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 是链接，其余都是静态行内标签。

参数

Badge 参数

Kbd

Mon, 01 Jan 0001 00:00:00 +0000

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

适用场景

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

快速开始

源码

GO-HTML-TEMPLATE

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

渲染结果

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

接口

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

GO-HTML-TEMPLATE

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

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

Fields 与 Field

Mon, 01 Jan 0001 00:00:00 +0000

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

适用场景

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

快速开始

源码

GO-HTML-TEMPLATE

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

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

渲染结果

搜索配置

offlineSearch , boolean , required , default: true: 构建本地搜索索引与命令面板。

组件参考

Mon, 01 Jan 0001 00:00:00 +0000

OINK 的组件分两类：每天都会用到的写作原语，和特定场景才需要的大型组件。跨多个页面的完整出版工作流位于场景组件。

所有组件都遵循同一套契约：语义化 HTML、非交互组件不加载 JavaScript、在打印和 Markdown 输出下都有明确的呈现方式、参数非法时构建直接失败而不是静默降级。

日常写作

组件	用途	需要 JS
代码块与代码分组	文件名、复制、折叠、同步标签页	有代码块的页面
Badge	Beta、Deprecated 之类的状态标签	否
Kbd	键盘快捷键	否
Fields	配置项、参数、返回字段说明	否
FileTree	目录结构	否

媒体

组件	用途	需要 JS
Gallery	多图网格	复用缩放运行时
图片缩放	点击放大截图与架构图	启用时按页加载

版式与结构

组件	用途
Tabs、Cards、Steps 等	标签页、卡片、步骤、折叠块、轮播

图表与可视化

组件	用途	运行时
图表与公式	Mermaid、KaTeX、Markmap、PlantUML	按页加载
ECharts	交互式数据图表	按页加载
Infographic	流程与信息图	按页加载

场景工作流

场景	协同能力
顺序阅读	翻页顺序、head 关系、本地数学公式
版本发布与下载	事实、校验和、滚动/固定渠道
Landing 页面	全宽外壳、本地数据、21 种分区
Book 出版	编号媒体、xref、索引、整本打印

这些场景会把多个原语与导航、数据和输出规则组合起来。对应页面是采用场景时的权威指南，不要只看一个 shortcode 示例就推断完整场景契约。

FileTree

Mon, 01 Jan 0001 00:00:00 +0000

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

适用场景

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

快速开始

源码

GO-HTML-TEMPLATE

{{< 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 >}}

渲染结果

仓库结构

content
- _index.md
- docs
  - operations-and-troubleshooting
    - a-deliberately-long-runbook-filename-that-wraps-without-horizontal-overflow.md
  - configuration.md
- blog
  - release.md
hugo.yml

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

Gallery

Mon, 01 Jan 0001 00:00:00 +0000

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

适用场景

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

快速开始

源码

GO-HTML-TEMPLATE

{{< 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 >}}

渲染结果

OINK 截图与布局示例

具有已知固有尺寸的全局图片资源。
这段刻意加长的说明文字用于演示桌面端和移动端都能正常换行，不会遮挡相邻图片或撑宽文档。
窄视口会自动减少响应式网格的实际列数。

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

Image Zoom

Mon, 01 Jan 0001 00:00:00 +0000

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

适用场景

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

启用功能

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

YAML

params:
  ui:
    image_zoom:
      enable: true

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

YAML

params:
  ui:
    image_zoom:
      enable: false

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

快速开始

源码

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

短代码

Mon, 01 Jan 0001 00:00:00 +0000

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

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

短代码分隔符

Hugo 支持两种形式：

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

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

`blocks/*` 短代码

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

`blocks/cover`

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

MARKDOWN

{{< 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。即使背景无法显示，首屏关键信息也必须保持可读。

图表与公式

Mon, 01 Jan 0001 00:00:00 +0000

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

使用 KaTeX 支持 LaTeX

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

行内公式

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

独立显示公式

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

MARKDOWN

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

E = mc^2

启用 KaTeX 支持

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

Apache ECharts

Mon, 01 Jan 0001 00:00:00 +0000

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

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

快速开始

GO-HTML-TEMPLATE

{{< 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 初始化脚本。

使用 AntV 创建信息图

Mon, 01 Jan 0001 00:00:00 +0000

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

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

快速开始

GO-HTML-TEMPLATE

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

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

语法结构

信息图通常包含：

组件 on OINK

代码块与代码组

增强围栏

实时效果

外壳参数

Badge

适用场景

快速开始

源码

渲染结果

参数

Kbd

适用场景

快速开始

源码

渲染结果

接口

Fields 与 Field

适用场景

快速开始

源码

渲染结果

组件参考

日常写作

媒体

版式与结构

图表与可视化

场景工作流

FileTree

适用场景

快速开始

源码

渲染结果

Gallery

适用场景

快速开始

源码

渲染结果

Image Zoom

适用场景

启用功能

快速开始

源码

短代码

短代码分隔符

blocks/* 短代码

blocks/cover

图表与公式

使用 KaTeX 支持 LaTeX

行内公式

独立显示公式

启用 KaTeX 支持

Apache ECharts

快速开始

Oink 如何加载图表

使用 AntV 创建信息图

快速开始

语法结构

`blocks/*` 短代码

`blocks/cover`