代码块与代码组
为 Hugo 代码示例添加文件名、精确复制、换行、折叠与可分享的代码组。
组件参考
写文档时可用的全部组件，按使用频率排列。
分类:
OINK 的组件分两类：每天都会用到的写作原语，和特定场景才需要的大型组件。跨多个页面的完整出版工作流位于场景组件。
所有组件都遵循同一套契约：语义化 HTML、非交互组件不加载 JavaScript、在打印和 Markdown 输出下都有明确的呈现方式、参数非法时构建直接失败而不是静默降级。
日常写作
| 组件 | 用途 | 需要 JS |
|---|---|---|
| 代码块与代码分组 | 文件名、复制、折叠、同步标签页 | 有代码块的页面 |
| Badge | Beta、Deprecated 之类的状态标签 | 否 |
| Kbd | 键盘快捷键 | 否 |
| Fields | 配置项、参数、返回字段说明 | 否 |
| FileTree | 目录结构 | 否 |
媒体
版式与结构
| 组件 | 用途 |
|---|---|
| Tabs、Cards、Steps 等 | 标签页、卡片、步骤、折叠块、轮播 |
图表与可视化
| 组件 | 用途 | 运行时 |
|---|---|---|
| 图表与公式 | Mermaid、KaTeX、Markmap、PlantUML | 按页加载 |
| ECharts | 交互式数据图表 | 按页加载 |
| Infographic | 流程与信息图 | 按页加载 |
场景工作流
| 场景 | 协同能力 |
|---|---|
| 顺序阅读 | 翻页顺序、head 关系、本地数学公式 |
| 版本发布与下载 | 事实、校验和、滚动/固定渠道 |
| Landing 页面 | 全宽外壳、本地数据、21 种分区 |
| Book 出版 | 编号媒体、xref、索引、整本打印 |
这些场景会把多个原语与导航、数据和输出规则组合起来。对应页面是采用场景时的权威指南，不要只看一个 shortcode 示例就推断完整场景契约。
共同约定
- 使用标准短代码写法
{{< … >}} - 嵌套名称（
filetree/folder、gallery/image、field）只能出现在对应父组件内部 - 参数非法会中断构建，并报出源码位置——严格失败优于静默降级
- 只有 Fields 的描述接受 Markdown，其余公开字符串参数一律按纯文本处理
- 页面没用到的组件，其运行时不会被下发
Badge
使用紧凑的语义状态标签，无需自定义颜色或 JavaScript。
Kbd
使用具备无障碍语义的静态按键序列编写快捷键。
Fields 与 Field
使用响应式语义 HTML 描述配置、参数、属性与响应字段。
FileTree
使用语义化渐进展开列表展示仓库与目录结构。
Gallery
使用响应式静态网格组织相关图片，并可复用 Image Zoom。
Image Zoom
使用可选的原生对话框查看有意义的独立图片细节。
短代码
安全、无障碍地使用 OINK 的本地优先内容组件。
图表与公式
在页面中添加本地图表、思维导图与科学公式。
Apache ECharts
使用结构化 JSON 或 YAML 创建响应式、本地优先图表。
使用 AntV 创建信息图
把简洁的声明式数据转换成本地 SVG 信息图。