组件 on OINK

提示块

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

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

图片

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

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

代码块

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

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

标签页

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

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

组件总览

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

这一栏回答一个问题：某个组件在 Markdown 里怎么写。每页的顺序相同：最简例子、逐步深入的例子、输出形态、参数表、限制。查语法见下面的速查表。

两种形态

组件的第一形态是 Markdown 语法本身：块引用、列表、表格、图片、围栏，加上紧跟其后的一行 {…} 属性。原生形态在 GitHub 与任意 Markdown 编辑器中仍然可读，Markdown 输出保留的也是源码。

表格

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

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

参数表

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

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

步骤

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

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

卡片

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

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

文件树

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

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

公式

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

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

Mermaid

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

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

PlantUML

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

plantuml 围栏里写 PlantUML 源码，浏览器把源码压缩编码后拼在一个 PlantUML 服务的 URL 后面，换回一张 SVG。适合需要完整 UML 表达力的时序图、类图、组件图、活动图与用例图。渲染依赖一个渲染服务：主题不提供默认端点，enable: true 却没给 svg_image_url 会让构建失败；没有可用服务时改用 Mermaid。

思维导图

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

markmap 围栏的正文是一段普通的 Markdown 大纲：标题与列表决定层级，浏览器把它画成一棵可展开、可折叠的树。适合把「这一节讲了什么」的层级一次呈现。节点之间有方向、有条件的流程用 Mermaid。

Draw.io

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

Draw.io 集成没有围栏也没有 shortcode，用的是普通 Markdown 图片。Draw.io 导出时勾上「Include a copy of my diagram」，SVG 或 PNG 里会带一份 mxfile 源码；主题的运行时识别这份副本后，给图片加一个编辑按钮。适合需要读者取走修改的图；只用于展示的图按普通图片处理。

ECharts

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

echarts 围栏的正文是一段 YAML 或 JSON 的 ECharts 选项对象，不是代码。适用于需要坐标轴、序列与图例的定量图表；只表达关系与流程时用 Mermaid，只表达顺序与层级时用 Infographic。Hugo 在构建期解析选项，解析失败则构建失败；浏览器用随主题分发的 ECharts 绘图，只有用到它的页面加载运行时。

Infographic

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

infographic 围栏挑一个 AntV 模板，把「标题 + 一串条目」渲染成信息图。适用于表达顺序、层级与对比这类结构。需要坐标轴与数值精度时用 ECharts，需要条件分支的流程时用 Mermaid。围栏正文是数据，在 GitHub 上仍是一段可读的文本。

最简例子

第一行是 infographic 模板名，其后是一个 data 块：title 是标题，items 下面每个条目至少要有 label。

画廊

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

画廊（Gallery）把一组相关图片排成响应式网格，围栏里每行一张图。适用于同一件事的几个视图：几张截图、几种状态、几套配色。单张图用图片；相互之间没有顺序与对比关系的图片不适合放进同一个画廊。

最简例子

围栏里一行一张图，语法是 Markdown 的 ![替代文字](来源)。

徽章

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

徽章（Badge）是紧跟在名字旁边的行内状态标签：Beta、已弃用、v0.5、需自建服务。适用于一两个词能说完的状态；作者只选语义 tone，颜色由主题决定，浅色与深色模式下的对比度都有保证。状态需要解释、操作步骤或截止日期时，改用正文或提示块。

按键

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

按键（Kbd）把读者要按下的键与正文区分开。适用于快捷键与组合键：一个按键一个位置参数，主题负责画框、补分隔符，并给读屏器一个可读的序列。命令名、选项名与要输入的文本用行内代码，它们不是物理按键。

引用

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

三个 shortcode 各做一件事：include 把另一个文件的内容放进当前页面，param 打印一个页面或站点参数，comment 丢弃一段内容。适用于跨页复用的片段与散落在多页的常量：同一段安装步骤出现在三页时用 include，版本号出现在几十页时用 param，改一处即可。只在一页出现的内容写在那一页。

Asciinema

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

asciinema 把一段 .cast 录像渲染成页面里的终端播放器。适用于命令行流程的演示：终端里的文字仍然是文字，可以选中复制，一段六分多钟的安装过程约 190 KB。图形界面的操作用截图或视频，本组件只播放终端录像。播放器与样式随主题分发，构建期不下载、运行期不连 CDN，只有用到它的页面、且只在 HTML 输出里加载这套运行时。