分类: 组件

asciinema 把一段 .cast 录像渲染成页面里的终端播放器。适用于命令行流程的演示：终端里的文字仍然是文字，可以选中复制，一段六分多钟的安装过程约 190 KB。图形界面的操作用截图或视频，本组件只播放终端录像。播放器与样式随主题分发，构建期不下载、运行期不连 CDN，只有用到它的页面加载这套运行时。 最简例子 只有 file 是必填的： 源码 {{< asciinema file="images/install.cast" >}} images/install.cast 这段录像是 …

三个 shortcode 各做一件事：include 把另一个文件的内容放进当前页面，param 打印一个页面或站点参数，comment 丢弃一段内容。适用于跨页复用的片段与散落在多页的常量：同一段安装步骤出现在三页时用 include，版本号出现在几十页时用 param，改一处即可。只在一页出现的内容写在那一页。 最简例子 include 只有一个必填参数 file： 源码 {{< include file="parts/install-oink.zh.md" >}} 被引的文件是一段普通 …

按键（Kbd）把读者要按下的键与正文区分开。适用于快捷键与组合键：一个按键一个位置参数，主题负责画框、补分隔符，并给读屏器一个可读的序列。命令名、选项名与要输入的文本用行内代码，它们不是物理按键。 最简例子 源码 按 {{< kbd "Ctrl" "K" >}} 打开命令面板。 按 Ctrl+ 加 K 打开命令面板。 参数必须加引号，一个按键一个参数。少于一个按键、空字符串、命名参数都会让构建失败。 单个按键 一个参数对应一个键，符号键按原样写。 源码 {{< kbd "Escape" >}} …

徽章（Badge）是紧跟在名字旁边的行内状态标签：Beta、已弃用、v0.5、需自建服务。适用于一两个词能说完的状态；作者只选语义 tone，颜色由主题决定，浅色与深色模式下的对比度都有保证。状态需要解释、操作步骤或截止日期时，改用正文或提示块。 最简例子 源码 {{< badge text="Beta" tone="warning" >}} Beta text 是唯一必填参数，必须是非空字符串。 五种 tone 只有这五个取值，没有自定义颜色。 源码 {{< badge text="默认" …

画廊（Gallery）把一组相关图片排成响应式网格，围栏里每行一张图。适用于同一件事的几个视图：几张截图、几种状态、几套配色。单张图用图片；相互之间没有顺序与对比关系的图片不适合放进同一个画廊。 最简例子 围栏里一行一张图，语法是 Markdown 的 。 源码 ```gallery   ``` 替代文字必须写：它 …

infographic 围栏挑一个 AntV 模板，把「标题 + 一串条目」渲染成信息图。适用于表达顺序、层级与对比这类结构。需要坐标轴与数值精度时用 ECharts，需要条件分支的流程时用 Mermaid。围栏正文是数据，在 GitHub 上仍是一段可读的文本。 最简例子 第一行是 infographic 模板名，其后是一个 data 块：title 是标题，items 下面每个条目至少要有 label。 源码 ```infographic infographic …

echarts 围栏的正文是一段 YAML 或 JSON 的 ECharts 选项对象，不是代码。适用于需要坐标轴、序列与图例的定量图表；只表达关系与流程时用 Mermaid，只表达顺序与层级时用 Infographic。Hugo 在构建期解析选项，解析失败则构建失败；浏览器用随主题分发的 ECharts 绘图，只有用到它的页面加载运行时。 最简例子 一个柱状图只需要三段：xAxis、yAxis、series。下面是本站文档六个栏目各有多少页。 源码 ```echarts …

Draw.io 集成没有围栏也没有 shortcode，用的是普通 Markdown 图片。Draw.io 导出时勾上「Include a copy of my diagram」，SVG 或 PNG 里会带一份 mxfile 源码；主题的运行时识别这份副本后，给图片加一个编辑按钮。适合需要读者取走修改的图；只用于展示的图按普通图片处理。 最简例子 写法与普通图片相同，文件名不受限制，.drawio.svg 只是惯例。 源码 ![Hugo 构建流水线：content 目录经 Hugo 产出 …

markmap 围栏的正文是一段普通的 Markdown 大纲：标题与列表决定层级，浏览器把它画成一棵可展开、可折叠的树。适合把「这一节讲了什么」的层级一次呈现。节点之间有方向、有条件的流程用 Mermaid。 最简例子 源码 ```markmap # OINK ## 本地优先 - 运行时全部随主题分发 - 不依赖任何 CDN ## Markdown 原生 - 组件是围栏和属性行 - 不写 shortcode 也能用 ## 四态输出 - HTML - 打印 - Markdown - RSS …

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

mermaid 围栏把一段文本渲染成流程图、时序图、甘特图、类图、ER 图与状态图。图以源码形式存在，可以进 Git、可以 review diff、可以被搜索命中；渲染由主题自带的 Mermaid 在读者浏览器里完成，不请求外部服务。需要像素级控制的示意图画成 SVG，按图片使用。 最简例子 源码 ```mermaid flowchart LR 内容["content/"] --> Hugo 配置["hugo.yml"] --> Hugo 主题["OINK 主题"] --> Hugo Hugo …

公式由 KaTeX 在构建期渲染成 HTML + MathML，页面只额外加载一份本地 KaTeX 样式表，没有 JavaScript，也不请求远程数学服务。行内公式写 \(…\)，块级公式写 $$…$$、\[…\]，另有 math 与 chem 两种围栏。需要 TikZ 绘图或 KaTeX 不支持的宏包时，改用预渲染的图片。 最简例子 行内公式写在句子中，前后的空格与标点留在分隔符外面。 源码 共享缓冲区命中率是 \(\mathrm{hit} = \frac{H}{H + R}\)，其中 …

文件树（FileTree）是一个 filetree 围栏，围栏正文就是目录清单：缩进表示层级，结尾的 / 表示目录，# 之后是注释。适合解释一份目录结构里与读者有关的那部分，并逐条加上说明。需要读者逐字复制的清单用普通代码块。 最简例子 源码 ```filetree - content/ - _index.zh.md - docs/ - blog/ - hugo.yml - go.mod ``` content/_index.zh.mddocs/blog/hugo.ymlgo.mod项目符号 …

卡片（Cards）是一组并列的链接：每张卡片一个链接标题加一句描述，网格随容器宽度自适应。适合栏目首页、「接下来读什么」与几条并列路径的入口。不适合排版正文段落（用普通段落）或做图片墙（用画廊）。 最简例子 带 {.cards} 的链接列表就是卡片。链接是标题，— 之后是描述。 源码 - [快速上手](/zh/docs/start/) — 克隆这个文档站，删掉不需要的页面，替换为你的站点信息。 - [创作内容](/zh/docs/write/) — 页面怎么组织、front matter 有哪些 …

步骤（Steps）是带编号圆点与竖线的有序列表：一个普通有序列表，加一行 {.steps} 标记，编号圆点与串起它们的竖线由 CSS 绘制，不加载脚本。用于有先后的操作流程。并列而无先后的内容用普通列表或卡片。 写法有两种：有序列表加 {.steps}（默认选它），以及 {{% steps %}} shortcode，每一步要有自己的标题、标题还要进右侧目录时用它。 最简例子 每一项都写 1.，让 Markdown 自己数。这样插入、删除、调换步骤都不用手改编号，而且内容缩进恒定是三个空格。 源 …

参数表（Fields）把「一串具名值 + 元数据 + 说明」渲染成响应式定义列表：名称独占一行，类型、是否必填、默认值是名称旁边的小字，说明另起一行，每一条自带锚点。用于配置项、命令参数与 API 字段。要按同一批列横向比较很多行时用普通表格，内容是操作顺序时用步骤。 写法有两种：普通表格加 {.fields}（默认选它），以及 fields/field shortcode（说明需要多个段落、列表或代码块时才用）。两种形态渲染出相同的条目。 最简例子 一张至少两列的管道表格，下一行写 …

表格是普通的 GFM 管道表格。主题的表格渲染钩子把每张表包进一块可横向滚动的区域，表格下面那一行 {…} 属性决定它是哪一种表：带标题的表、兼容矩阵、参数表、编号表或标签页。合并单元格、排序与筛选不在能力范围内，需要它们的场景请改换呈现方式。 最简例子 不写属性行就是一张普通表。对齐方式照旧来自分隔行，表头单元格是 th scope="col"。 源码 | 组件 | 端口 | 用途 | | --- | :---: | --- | | PostgreSQL | 5432 | 数据库 | | …

这一栏回答一个问题：某个组件在 Markdown 里怎么写。每页的顺序相同：最简例子、逐步深入的例子、输出形态、参数表、限制。查语法见下面的速查表。 两种形态 组件的第一形态是 Markdown 语法本身：块引用、列表、表格、图片、围栏，加上紧跟其后的一行 {…} 属性。原生形态在 GitHub 与任意 Markdown 编辑器中仍然可读，Markdown 输出保留的也是源码。 原生形态表达不了的场景使用 shortcode：正文标签页、带块级描述的参数表、带图标与徽章的卡片、终端录像。规则有五 …

标签页并列等价的几种写法：包管理器、发行版、YAML / TOML / JSON、环境变量与配置项。有先后的步骤、互不相关的内容不适合标签页，读者一次只看见其中一个。 原生形态是给相邻的块加 tab 属性。正文（多个段落、列表、提示块）要做成标签页时才用 tabs/tab shortcode。两种形态共用一个运行时、一套 DOM 与一样的键盘行为。 最简例子 连着写两个带 tab 的围栏，中间只隔空行。 源码 ```bash {tab="Homebrew"} brew install hugo …

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

图片只有一种写法：Markdown 的 。独立成段的图片可以在下一行跟一行 {…} 属性，成为带图注的 figure、缩放候选、编号图或经 Hugo 处理的派生图。主题没有图片 shortcode。 最简例子 源码  这张图与本页放在同一目录（页面包）中，主题读取它的固有尺寸并写入 width/height，页面加载时不发生跳版；所有图片懒加载。替代文字供屏幕阅读器与搜索引擎使用，应当 …

提示块（Callout）是 GitHub / Obsidian 风格的块引用：> [!TYPE] 起头，正文跟在后面。用于把提示、警告、前提条件从正文中分离出来；正文一句话能说清的内容不必使用提示块。 最简例子 源码 > [!NOTE] > Hugo Module 需要本机安装 Go；只用离线归档时不需要。 说明 Hugo Module 需要本机安装 Go；只用离线归档时不需要。 不写标题时使用本地化的类型名（中文站显示「注意」，英文站显示 “Note”）。源码在 GitHub 上按 …