短代码

安全、无障碍地使用 OINK 的本地优先内容组件。
分类:

短代码用于表达普通 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。即使背景无法显示，首屏关键信息也必须保持可读。

blocks/lead

创建醒目的介绍区块：

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

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

blocks/section

创建通用落地页区块：

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

### 一个分区

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

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

blocks/feature

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

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

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

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

导航栏下方布局校正

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

辅助短代码

alert

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

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

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

告警、缩进与示例

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

pageinfo

在 Markdown 外渲染信息面板：

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

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

imgproc

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

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

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

swaggerui

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

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

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

redoc

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

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

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

iframe

嵌入另一个页面：

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

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

OINK 内容组件

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

details

创建无障碍折叠内容：

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

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

steps

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

创建内容

每一步先写一个直接子标题，再在标题后添加属于该步骤的任意 Markdown 内容。

检查顺序

整体移动、新增或删除步骤；显示的序号会自动更新。

发布结果

在窄屏和两种配色主题下检查这组步骤。

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

MARKDOWN 
{{% steps %}}

### 创建内容

添加第一条说明。

### 检查顺序

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

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

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

### 发布结果

添加最后一条说明。

{{% /steps %}}

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

asciinema

播放 asciinema .cast 录像：

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

窗口标题优先使用 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 是完整的可视化系统，无法用一个段落说明清楚。高级特性指南会完整介绍包装层、结构化选项、主题、响应式行为、无障碍与可信回调边界：

短代码正文接受 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：

MARKDOWN 
{{< 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-card 放入支持键盘滚动的轮播：

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

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

param

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

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

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

标签页

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

MARKDOWN 
{{< 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 短代码：文本内容

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

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

card 短代码：程序代码

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

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

卡片组

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

引入外部文件

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

复用文档

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

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

安装

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

引入代码文件

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

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

错误报告

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

条件文本

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

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

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

最后修改 2026年8月14日 · chore: update site to OINK v0.4.1 (911d6a9)