创作内容

• 1: 编写页面
• 2: 组织内容
• 3: 页面参数
• 4: 博客与文章
• 5: 书籍出版
• 6: 发布与下载页
• 7: API 文档

---
title: 安装 Pigsty
linkTitle: 安装
description: 在一台干净的 EL 9 机器上装出可用的 PostgreSQL 集群。
weight: 20
---

## 前提条件 {#prerequisites}

一台能 SSH 登录的 Linux 机器，`sudo` 免密，Python 3.11 或更高版本。

> [!IMPORTANT]
> 安装脚本会改写 `/etc/yum.repos.d/`，先备份。

1 - 编写页面

本页覆盖一页文档的完整写法：文件位置、front matter、标题锚点、链接、图片、草稿与页尾。前提是站点已能本地构建，尚未搭起时先看十分钟上手。

新建一页

页面是 content/ 下的 Markdown 文件，URL 由它在 content/ 里的位置决定：content/docs/install.md 发布为 /docs/install/。中文译文是同目录下的 .zh.md 同名文件，与英文页共享同一条逻辑路径。

没有附带资源的页面写成单个文件。页面带图片、cast、示例配置这类资源时改成一个目录，页面本身命名为 index.md，资源与它同放，这是 Hugo 的页面包（page bundle）：

hugo new content docs/install.md 用 archetype 生成一个带 front matter 的空文件，见 Hugo 文档；手写文件同样可行。

必要的 front matter

文件开头两行 --- 之间是 YAML front matter。四个键每页都应写上：

---
title: 安装 Pigsty          # 页面大标题、浏览器标题、搜索结果标题
linkTitle: 安装             # 侧栏与面包屑里的短名，省略时用 title
description: 在一台干净的 EL 9 机器上装出可用的 PostgreSQL 集群。
weight: 20                  # 同级页面的排序，用 10 的倍数留出插入空间
---

description 用一句话说清这页让读者做成什么。它出现在栏目首页的卡片、搜索结果与社交卡片中。weight 决定侧栏顺序，weight 相同时才退回字母序。

其余的键可选：图标、草稿、搜索权重、评论开关、页面外壳等，全表见页面参数。

标题层级与稳定锚点

正文用 ## 开始分节，# 留给 title。主题已渲染页面大标题，正文里再写一个 # 会出现两个一级标题。右栏的页面目录从 ## 开始收，收到第几级由 Hugo 的 markup.tableOfContents 决定，本站是 ####。

每个 ## 与 ### 都要手写英文锚点 {#id}：

## 前提条件 {#prerequisites}

### 磁盘与内存 {#disk-and-memory}

理由有两条：

• 中英对齐。Hugo 从标题文字生成 ID，中文标题生成中文 ID：/docs/install/#prerequisites 与 /zh/docs/install/#前提条件 指向同一个语义位置，却是两个锚点，翻译审计无法比对。译文标题写上英文页的 ID，两边即同一个片段。
• 链接稳定。标题文字会随措辞调整而改变，公开链接不应随之失效。显式 ID 一旦发布即视为公开路由；需要改名时保留旧 ID 的空锚点：

## 快速开始 <a id="get-started"></a> {#quickstart}

ID 用短横线小写英文，全页唯一。本站的翻译审计脚本会比对英文页与中文页渲染出的标题 ID，不一致就报错。

链接写法

三种写法，用途不同：

三种写法都带尾部斜杠，指向目录形式的路由（/zh/docs/write/pages/），与 Hugo 的默认永久链接一致。

主题没有链接渲染钩子，链接原样交给 Goldmark：外链不会自动加 target="_blank"，需要新标签页时写成 HTML，或在站点自己的 layouts/_markup/render-link.html 里处理。

普通 Markdown 链接不做存在性检查。因此：

• 站内链接优先写绝对路径，改结构后用 grep 全站替换；
• 移动页面时给旧路径加 aliases，同时把站内链接改到新路由，不要让 alias 长期承担导航；
• 拿不准的目标用 ref，让构建替你检查。

双语页面链接到逻辑页面（/zh/docs/write/pages/），不要链接 .zh.md 文件名；片段 ID 保持语言中立。

图片位置

页面自己的截图放页面包，多页共用的图放 assets/images/，不需要处理的大文件放 static/。三处在源码里都写成 ![替代文字](来源)，属性行控制图注、尺寸、缩放与编号，见图片。

草稿与发布

draft: true 的页面不会进入构建产物：

---
title: 尚未定稿的迁移指南
draft: true
---

预览时用 hugo server -D 显示草稿（-D 即 --buildDrafts）。date 写在未来的页面同样被排除，用 -F 显示。生产构建不加这两个开关，hugo 默认只发布已定稿的内容。

OINK 的 Markdown 扩展一览

正文是标准 Markdown（Goldmark），加上下面这些原生形态。它们都是普通 Markdown 语法加一行属性，在 GitHub 上按源码阅读同样可读：

剩下的少数组件（徽章、按键、引用文件、终端录像、Book 的图表式例）用 shortcode，语法与参数见组件总览。

组合例子：步骤里放代码围栏与提示块。

1. 安装 Hugo Extended，最低 0.160.1：
   ```bash
   brew install hugo
   ```
1. 克隆文档站并预览：
   ```bash
   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs && hugo server
   ```
   > [!TIP]
   > 加 `-D` 连草稿一起预览。
{.steps}

1. 安装 Hugo Extended，最低 0.160.1：

   brew install hugo

2. 克隆文档站并预览：

   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs && hugo server

   提示

   加 -D 连草稿一起预览。

页尾的自动内容

页面末尾的四块内容由主题按固定顺序生成，不必在正文里写：

标题旁边的操作菜单（复制 Markdown、编辑本页、查看历史、提 issue、打印）也是自动的，同样在仓库与页面信息里配置。

单页关闭其中某一块用 front matter：feedback: false、annotation: false、pager: false、comments: false。键的含义见页面参数。

验证

写完一页，运行一次严格构建：

hugo --printPathWarnings --panicOnWarning

• 输出必须以 Total in … 结束，没有 ERROR、没有 WARN。属性行写了不允许的键、组件参数非法、ref 目标不存在，都在这一步失败并指出文件与行号；主题不做静默降级。
• --printPathWarnings 报出两个页面指向同一输出路径的情况，多语言站或改过 permalinks 时较常出现。

在浏览器里确认三项：

1. 侧栏里出现了这一页，位置符合 weight；
2. 右栏目录列出了你写的 ##，点击后 URL 里的锚点是英文；
3. 中英两个版本的同名标题锚点一致（本站有 node scripts/check-doc-translations.mjs --public public 做这项审计）。

相关

• 组织内容 — 目录结构如何决定侧栏
• 页面参数 — front matter 全表
• 组件总览 — 每个组件的语法与参数
• 多语言 — 双语对等文件与缺译回退
• 本地预览 — hugo server 的常用开关

2 - 组织内容

OINK 不需要单独配置导航：content/ 下的目录结构就是侧栏树。本页覆盖目录与文件的摆放、栏目首页、排序、图标、折叠、隐藏，以及多根侧栏。

目录就是侧栏

一个目录是一个栏目（Hugo 称 section），目录里的 Markdown 文件是它的页面，嵌套目录是它的子栏目。侧栏按这棵树逐层渲染，顺序由 weight 决定，标签取 linkTitle，缺省时取 title。左侧这棵树的源码如下：

每个目录都要有 _index.md

栏目首页是目录里的 _index.md（中文为 _index.zh.md）。缺少它时 Hugo 仍会生成栏目，但没有标题、描述、图标与 weight：侧栏那一行显示目录名，排序不受控制。

---
title: 部署上线
linkTitle: 部署
description: 把站点发布到 GitHub Pages、Cloudflare Pages 或自己的 Nginx。
weight: 50
icon: fa-solid fa-cloud-arrow-up
---

栏目 _index.md 另有一项专属能力：用 cascade 把共享设置一次下推给整棵子树，不必每页重复。

---
title: 参考
weight: 90
cascade:
  pager: false        # 这个子树里的页面都不显示上一页 / 下一页
  search_boost: 0.8   # 参考页在搜索里排后一点
---

排序：weight 用 10 的倍数

同一栏目里的页面按 weight 升序排列，weight 相同时才退回日期与 linkTitle 字母序。一律用 10 的倍数（10、20、30），此后往中间插页不必改动其它页。栏目自身的 weight 决定它在父级里的位置。

没写 weight 的页面视为 0，Hugo 把它们排在所有写了 weight 的页面之后，彼此按日期与标题排列。这个顺序会随内容改动漂移，因此每页都写上 weight。

单文件还是页面包

没有自身资源的页面用单文件 slug.md；带图片、cast、示例文件的页面改成目录加 index.md，资源与它同放。两种形态在侧栏里没有区别，URL 也相同。详见编写页面。

栏目首页显示子页列表还是卡片

_index.md 的正文之后，主题自动接上子页索引，两种样式：

params:
  ui:
    section_index: cards # list | cards

list 是主题默认，每个子页一行标题加描述；cards 是链接卡片网格，读取子页的 icon、linkTitle 与 description。本站用 cards，本栏目首页即是例子。单个栏目需要另一种样式时在它的 front matter 里覆盖：

section_index: list
cascade:
  section_index: list   # 连同后代栏目一起

两个页面级开关不受样式影响：simple_list: true 渲染紧凑的项目符号列表，no_list: true 不生成索引，用于正文自行手写导航的场合。

侧栏图标

在页面或栏目的 front matter 里写一对 Font Awesome class：

icon: fa-solid fa-cloud-arrow-up

图标密度是站点级策略，用于避免叶子页全部带图标：

params:
  ui:
    sidebar_icon_policy: groups # all | groups | none

新站点建议显式写 groups：保留分组的语义标识，去掉叶子层的图标。本站使用这个设置，左侧只有六个栏目带图标。

展开与折叠

有子页的栏目在侧栏里带一个折叠箭头，读者的展开状态保存在本地。默认行为：当前页所在的那条路径展开，其余收起；博客类栏目默认展开。

sidebar_expanded: true   # 这个栏目始终默认展开

站点级的折叠、紧凑模式、初始展开层数、宽度与截断在布局与页面类型里配；键的完整定义见配置总览。

从侧栏里藏起来

toc_hide 与 hide_summary 控制两个不同的入口，两处都不该出现时才同时设置。

外壳由 type 决定，不是路径

文档外壳（侧栏、目录、面包屑、翻页器）不取决于目录名，只取决于页面的 type 是否在 params.ui.shell_types 里：

params:
  ui:
    shell_types: [docs, book, blog, swagger]

文档因此可以放在任意路径，用 cascade 指定 type 即可。例如把一套手册放在 content/handbook/，栏目根的写法如下：

---
title: 运维手册
type: docs
sidebar_root_for: self      # 侧栏树的根即本栏目，不回退到 /docs
cascade:
  type: docs                # 整棵子树都用文档外壳
---

多根侧栏

侧栏树默认以读者所在的顶层栏目为根，树上方一行标出当前的根。规模较大的子树可以自己成为一个根，例如带版本的 API 参考或一本独立的手册：

---
title: API 参考 v2
sidebar_root_for: self   # self | children
---

根节点上方的切换器是全站的：它列出所有顶层栏目，加上站内所有 sidebar_root_for: self 的栏目。只有一个入口时它退化成一个普通链接，两个及以上才是下拉菜单。顶层栏目不出现在切换器里时，在它的 _index.md 写 sidebar_root_menu: false。

切换器下方，栏目首页仍是树里的第一个链接：切换器选择一棵树，根链接指向一篇文档。sidebar_root_link_self: false 让根那一行改为指向父级栏目。

验证

hugo --printPathWarnings --panicOnWarning

必须 Total in …，没有 ERROR / WARN。--printPathWarnings 报出两个页面指向同一输出路径的情况，改目录结构时较常出现。

在浏览器里逐项确认：

1. 侧栏里的顺序与写下的 weight 一致，新栏目出现在预期位置；
2. 栏目首页的子页索引齐全（缺项来自 hide_summary 或缺少 _index.zh.md）；
3. 面包屑与翻页器的顺序与侧栏一致，翻页器读的是同一棵树；
4. 换语言之后树的形状相同（每个 _index.md 都要有 .zh.md 对等文件）。

侧栏条目超过 params.ui.sidebar_menu_truncate 时构建给出警告，并指出应调到多少。这个警告不可忽略：被截断的条目不会出现在侧栏里。

相关

• 编写页面 — 单页怎么写
• 页面参数 — 这页出现的每个 front matter 键的完整定义
• 布局与页面类型 — 站点级的外壳、侧栏与目录设置
• 导航与菜单 — 顶栏菜单、面包屑与翻页器
• 多语言 — 双语目录树怎么保持一致

3 - 页面参数

本页是页面级参数的全表，只列 OINK 主题会读取的键。Hugo 自身的 front matter 字段（slug、url、build、sitemap、expiryDate 等）照常可用，语义见 Hugo 文档。站点级参数（hugo.yml 里的 params.*）见配置总览。

表格说明

优先级从高到低：

1. 页面自己的 front matter；
2. 最近一层 cascade（多层 cascade 都设了同一个键时，离页面最近的那一层生效）；
3. hugo.yml 里的站点参数。

「默认」列标「站点值」的键，未写时回落到同名的站点参数。

页面键一律写在 front matter 顶层，键名是站点键去掉 ui. 前缀：站点的 params.ui.section_index 对应页面的 section_index。front matter 里不写 ui: 段，键一律在顶层。写在 ui: 段里的键不会被读取，也不会有任何提示——某个设置看着没生效时，先对照本页核一遍键名。

---
title: 兼容性矩阵
weight: 40
page_width: wide
footer_style: slim
image_zoom: true
section_index: list
---

放进 cascade 时键名不变，多包一层：

cascade:
  pager: false
  section_index: list

非法值不会中断构建。主题会发一条警告，指出键名、收到的值以及实际用了哪个回退值，然后按表里的默认值把这一页渲染出来——一个笔误只降级一个设置，而不是让 hugo server 下每个 URL 都返回 HTTP 500。它也不会因此混进线上：所有发布关卡都带 --panicOnWarning 构建，那条警告在真正要紧的地方仍然是硬失败。

少数几个键确实会中断构建，表里会写明。它们是那种「继续构建就会发布出错误内容」而不只是「发布出朴素内容」的情形：残缺的上游署名（半条声明读起来和完整的一模一样）、translation_notice、release 事实、落地页的 sections，以及任何解析不到目标的引用。

基本

侧栏与导航

指南在组织内容。

页面外壳

站点级的默认值与效果说明在布局与页面类型。

搜索

指南在全文检索。

输出形态

指南在 Agent 支持（.md 与 llms.txt）与打印支持。

页尾：评论、反馈与出处

顺序固定为反馈 → 出处 → 翻页器 → 评论，见编写页面。

上游出处

页面改写自别处的材料时，用 upstream_link 声明来源，页尾出处行会给出作品、版权人、许可证与完整声明的链接。这一族键的解析顺序是站点参数 → data/upstreams 中由 upstream_source 指名的条目 → 本页 front matter，最具体的声明胜出。

upstream_link 只从 front matter 读取（cascade 有效，站点参数无效）——站点级的值会让每一页都声称同一个来源。没有 upstream_link 却写了任何一个同族键，构建失败。

四个必填键（upstream_name、upstream_copyright、upstream_license、upstream_notice）缺一即构建失败：残缺的署名比明显的缺失更糟。主题自带一份 SPDX 表 data/licenses.yaml，站点用同名文件补充或覆盖条目。

图片缩放

博客与文章

指南在博客与文章。

Book

指南在书籍出版。整本书通过栏目 cascade 设 type: book。

Landing

指南在首页与落地页。任意页面写 layout: landing 就用落地页外壳。

发布页

指南在发布与下载页。栏目写 layout: releases 后忽略 weight，按发布日期与 SemVer 倒序排列。

相关

• 编写页面 — 每页都要写的那几个键
• 组织内容 — 侧栏与导航键的实际效果
• 配置总览 — hugo.yml 里的站点参数全表

4 - 博客与文章

博客文章与文档页的正文写法相同，区别在外壳：文章带日期、作者、标签与封面图，列表按年份倒序排列，栏目带 RSS。本页覆盖博客栏目的建立、文章 front matter、封面图、列表分页与 Feed。

博客目录结构

博客是 content/ 下的一个栏目，type: blog 使它使用博客外壳。子目录按发布方与受众划分，文章平铺其中。不要建年份目录，年份分组由列表页自动生成：

栏目根把类型下推给整棵子树，并设定该栏目共用的行为：

---
title: 博客
description: OINK 工程实践与发布注记
type: blog
icon: fa-solid fa-blog
sidebar_root_for: self      # 博客有自己的侧栏树
cascade:
  type: blog
  feedback: false           # 文章不问「这页有帮助吗」
  comments: true            # 但开评论
---

params.ui.blog_section（默认 blog）指明博客根的位置。目录另起名字时改这个参数，或按上面的写法用 sidebar_root_for: self。

侧栏里博客栏目默认展开，条目按日期倒序；给某篇文章写上 weight 会把它固定在最前。

一篇文章的 front matter

---
title: Oink 0.4.0 — 面向完整发布流程的场景组件体系
linkTitle: Oink v0.4.0        # 侧栏与翻页器里的短名
date: 2026-08-14              # 发布日期，决定排序与分组
lastmod: 2026-08-14
description: >-
  Oink 0.4.0 交付连续阅读与发布界面、可复用 Landing 页面、
  带稳定引用的 Book 出版能力，以及键盘优先的站点外壳。
author: OINK 维护者
categories: [发布]
tags: [Oink, Release]
---

与文档页不同的几点：

• date 必填。它决定文章在列表里的位置、年份分组与 RSS 时间。写在未来的日期默认不构建，hugo server -F 可以预览。
• description 渲染成正文上方的导语，不只是搜索摘要，因此写成给读者阅读的一句话。
• author 支持行内 Markdown，可以写成 [Vonng](https://vonng.com)。需要多位作者、头像或作者主页时，改用下面的 authors taxonomy；两者互不干扰，没写 authors 的文章照旧渲染 author。
• 日期显示格式由 params.time_format_blog 决定，可以按语言分别设置（本站英文是 Monday, January 02, 2006，中文是 2006年1月2日）。

双语文章成对存放，两种语言的 date、author、weight、aliases 保持一致；标题、描述、标签要翻译，提交 ID、版本号、命令和 URL 不翻译。

封面图

列表页与标签页的每一行左侧有一张缩略图，按以下顺序解析，第一个命中的生效：

1. 文章 front matter 的 images，取第一项；
2. 页面包里文件名含 featured 的图片资源（会被裁切成缩略图，图片资源自己的 byline 会作为图注）；
3. 从祖先栏目 cascade 继承来的 images，就近生效。

栏目级默认封面用 Hugo 原生的 cascade 覆盖整棵子树，本站两个子栏目各设一张：

cascade:
  images: [/images/releasenote.webp]

某一篇不要封面时，在它的 front matter 写 images: []；整个子栏目都不要，就把 images: [] 写进那一层的 cascade。站点级的 params.images 不受影响 —— 它只做分享卡片，不会渲染成列表缩略图。

渲染到文章正文里

默认情况下，解析出来的这张图只出现在列表行与社交卡片里，文章本身什么都不显示——手写一个题图，迟早会和卡片对不上。params.ui.featured_image 让主题用同一个解析结果把它渲染出来：

params:
  ui:
    featured_image: banner

页面键是 featured_image，所以某个子栏目的 cascade 可以只为那棵树打开它，单篇文章也可以退出。没有题图的文章在两种模式下都不渲染任何东西——正因如此，一个题图有一搭没一搭的栏目也可以整体打开这个开关。两种模式都不引入脚本，也不增加打包成员。

cascade:
  featured_image: wash

列表页与分页

栏目 _index.md 的正文之后，主题自动接上文章列表：按年份分组（「撰写于 2026」），年份倒序，每条显示标题、日期、所属子栏目、标签、缩略图与正文前 250 字的摘要。

分页用 Hugo 原生的分页器，默认每页 10 篇，在 hugo.yml 里调整：

pagination:
  pagerSize: 20

取值与其余分页选项见 Hugo 文档。

卡片形态

params.ui.blog_index: cards 把同一份列表渲染成内容卡片网格而不是行列表：文章题图的 16:9 裁切在上，标题、日期与子栏目行居中，下面三行摘要。

params:
  ui:
    blog_index: cards
    blog_index_columns: 3

这个选择纯粹是呈现层面的——按年分组、分页与 manual_link 的行为完全一致，行列表那一路的输出一个字节都没变。列数只在 xl 断点以上生效；md 到 xl 之间恒为两列，md 以下一列。博客根目录的 front matter blog_index 或它的 cascade 可以按栏目设置。Term 页与 taxonomy 页保持行列表，读者侧没有在两种形态之间切换的开关。

卡片题图只要资源可处理就走 Hugo 的 .Fill，一屏卡片不会为此下载一堆原图。

RSS

哪些页面产出 Feed 由 outputs 决定。给 section 加上 RSS，每个栏目就有自己的 Feed：

outputs:
  home: [HTML, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

outputs 一旦写出就整体替换 Hugo 的默认值，RSS 必须显式写回。漏写等于关闭该类页面的 Feed，构建不会报错。

本站因此有 /zh/blog/index.xml（整个博客）与 /zh/blog/release/index.xml（只有发布注记）。栏目 Feed 递归包含所有子栏目的文章，订阅 /zh/blog/ 即可收到全部。单篇文章没有自己的 .xml。

每种语言有各自的 Feed，地址是该语言路由加 index.xml。条数上限由 Hugo 的 services.rss.limit 控制。在博客根与它的一级子栏目页上，标题行右侧操作按钮的首位是 RSS 链接，读者不必手拼地址。

全站不需要 Feed 时用 disableKinds 关闭这一类输出，比逐个页面类型删除 RSS 更彻底：

disableKinds: [RSS]

组件在 Feed 里退化成静态形态：折叠块展开、交互控件去掉。四态输出的规则对博客与文档一致。

分类与标签

tags 与 categories 是 Hugo 的分类体系，主题把它们渲染成文章头部的 chip、右栏的标签云和顶栏的筛选菜单。启用、双语标签与按内容类型开关见分类体系。

发布注记

带版本号的发布公告写成普通文章，惯例放在 blog/release/ 下，linkTitle 带版本号（Oink v0.4.0）。需要发布卡片、资产表与校验和的下载页见发布与下载页。

文章里用组件

提示块、标签页、代码块、图片、表格的用法与文档页相同，语法见组件总览。文章正文的标题同样写显式英文 {#id}。

文章末尾的反馈 / 最后修改 / 翻页器 / 评论四块与文档页一致，见编写页面。博客通常关闭反馈、保留评论。

作者与署名

声明这个 taxonomy 就是全部开关，主题不为此增加任何参数：

taxonomies:
  category: categories
  tag: tags
  author: authors

文章按顺序写出作者：

authors: [vonng, ada-example]

文章头部就按这个顺序渲染头像与带链接的名字——front matter 里的序列既是集合也是顺序——列表行渲染名字，博客 feed 为每篇文章的每位作者发一条 <dc:creator>，与站点级的 managingEditor 并存。名字之间用 CSS 的 gap 分隔而不是连接词，因为「和」是个逐语言的决定，而这里有 32 种语言。

作者主页就是 term 页本身，所以不存在另一份 data/authors 和它打架：

---
title: Vonng
description: OINK 与 Pigsty 的维护者。
images: [portrait.webp]
---

正文是长介绍，渲染在主页上名字下方。

显示名取的是 term 页的链接标题——写了 linkTitle 就用它，否则用 title——所以主页可以挂全名、署名处用短昵称。description 是一句话介绍，正文是长介绍，头像则是题图解析器为这一页选中的那张——images: 与页面包里的肖像文件，走的是文章题图那套同样的规则。双语主页就是旁边一个 _index.zh.md。文章写了、但没人给它建主页的名字照样出署名：链接标题、一个首字母，以及指向归档页的链接。

0.4 的 author: 字符串在没有 authors 的地方原样保留，两种写法互不告警。

系列

系列是一条穿过若干篇各自独立成文的文章的阅读路径。编号、交叉引用与聚合输出属于书籍，这里是更轻的那个东西。声明 taxonomy 同样就是全部开关：

taxonomies:
  series: series

文章写出系列名，也可以给自己定个位置：

series: [shell-internals]
series_weight: 20

它的正文上方就会出现一条横幅，写明系列名、自己是第几篇、下一篇是哪篇，以及折在 <details> 里的完整列表——不用 JavaScript，也不增加打包成员。term 页 content/series/<name>/_index.md 是系列的引言，旁边放一个 _index.zh.md 就成双语。

阅读顺序由主题自己算，因为 term 页给不出这个顺序：Hugo 的 taxonomy weight 既到不了 Page.Weight，也进不了 GroupByParam。带权重的成员按 series_weight 升序排在前，其余按日期升序跟在后面，同序时用 Path 决胜。横幅与 term 页读同一个解析结果，所以它们不可能对「第二篇是哪篇」有分歧——这也意味着系列 term 页是由旧到新排列的，和其它所有 term 页相反。这正是这个功能本身。

一篇文章属于多个系列时只显示一条横幅，取它写在最前面的那个系列。只有一篇的系列不显示横幅。

authors 与 series 都不出现在文章的通用 taxonomy 标签行里，因为它们各自有专门的呈现面。想把某一个放回去，就在 params.taxonomy.page_header 里写上它的名字。

分享

params.ui.share 在页尾最前面放一条分享栏。它默认为空，所以在站点写出目标之前什么都不渲染；写出来的顺序就是渲染顺序：

params:
  ui:
    share: [x, bluesky, mastodon, reddit, hackernews, email, copy]

可选的目标有十六个：x、bluesky、mastodon、facebook、linkedin、reddit、hackernews、telegram、whatsapp、line、pinterest、weibo、chatgpt、claude、email、copy。未知的名字告警并丢弃。Discord 是故意没有的：它根本没有公开的 share-intent URL，与其让主题去猜一个私有 scheme，不如用 copy 顶上。

页面键是 share，所以 cascade 可以把这条栏限定在一棵树里，页面自己的列表会整体替换继承来的那份，share: false 则让单页退出：

cascade:
  share: [x, bluesky, email, copy]

只有普通页面渲染分享栏——列表页、term 页与首页没有「唯一被分享的那个东西」——打印、Markdown 与 RSS 一概不带。

它不做什么，才是它能出现在这个主题里的原因。没有分享计数、没有平台 SDK、没有 iframe、没有第三方脚本或样式表——而那三样正是这类组件通常的形态：每一页都向一家读者从未选择过的公司发一次请求。每个目标都是一个纯粹的 <a href> intent 链接，只带这一页自己的 permalink 与标题，不挂任何投放参数，另加一个本地复制按钮。站点构建时不取任何东西，页面加载时也不取；一次分享唯一可能引发的请求，就是读者点下去之后自己发起的那次跳转。把十六个目标全开的构建，不加 --third-party 也能通过 bin/check-output-security.py。

chatgpt 与 claude 是把同一个构建期 permalink 交给助手，附一句「请读这一页」。它们不是页面操作菜单里的「在 ChatGPT 中打开」/「在 Claude 中打开」——那两条由运行时在激活时改写成浏览器里的实时 URL，因此留在 page_context_menu.assistant_links 后面。

复制按钮就是内置的 copy_link 动作，也就是说不管有没有配分享栏，命令面板在每个站点的每一页上都带着它。

验证

hugo --printPathWarnings --panicOnWarning

必须 Total in …，没有 ERROR / WARN。随后确认：

1. 文章出现在 /zh/blog/ 的正确年份分组里，日期显示为中文格式；
2. public/zh/blog/index.xml 存在，里面有这篇文章，链接是完整的绝对地址；
3. 缩略图出现在列表里（缺失说明三条封面来源都没命中）；
4. 标签 chip 能点进对应的标签页。

相关

• 编写页面 — 正文怎么写
• 页面参数 — author、images 等键的完整定义
• 组织内容 — 目录与侧栏
• 分类体系 — 标签与分类
• 发布与下载页 — 版本卡片与资产表

5 - 书籍出版

一本书是一棵 type: book 的内容树：目录决定章节顺序，front matter 决定章节编号，图 / 表 / 式 / 例各带一个手写编号与稳定锚点。交叉引用在四种输出里都能解析，书根页面可以生成整本打印 HTML。

前提两条：站点的 markup.goldmark 已开启属性行与 passthrough（见组件总览）；params.ui.shell_types 保留 book（主题默认包含）。

一本书的目录

书根是一个普通的 Hugo section，章是它的子目录，节是章里的页面。没有第二份章节清单：侧栏、翻页器、生成的目录读的都是这棵树。

章节编号手写：book_number 写什么就显示什么，主题不按目录顺序自动编号。图 / 表 / 式 / 例的 num 同理，是作者掌握的字符串（2-1、5.3、A-2 均合法），不是渲染时计算的序号。重排目录因此不会让已经印出去的编号漂移。

书首页与章首页

书根声明类型、级联给后代，并显式请求 print 输出。这项聚合输出构建代价高，主题不替消费站开启：

---
title: PostgreSQL 运维手册
type: book
book_number: B
cascade:
  type: book
outputs: [HTML, print, markdown]
---

分区书对应 Hugo 的 section 输出类型，书位于站点根时才用 home：

outputs:
  section: [HTML, print, markdown]
params:
  ui:
    sidebar_headings: 3     # 当前章节行下投射 h2–h3 标题树
    book_draft_banner: true # 草稿章节页首多一条本地化提示

章首页只需要编号与顺序：

---
title: 复制与故障切换
book_number: 2
book_status: draft
weight: 20
---

book_number 显示在页面标题、侧栏与生成目录里。book_status: draft 是可见的编辑状态标签，不改变 Hugo 的发布状态：草稿章节照常构建、照常发布。

sidebar_headings 接受 false、true（只到 h2）或 2–4 的最大层级。要被引用的标题一律写显式 ID，如 ## 同步复制 {#sync-replication}：自动生成的 slug 适合导航，不适合作为长期引用目标。

配置键的完整定义在配置总览，页面参数在页面参数。

编号：原生形态

四种编号对象各有一种原生形态：一个 Markdown 块，紧跟其后一行属性行。属性行里 num= 是编号，#id 是锚点，caption= 是纯文本题注。

图

图片块后面跟属性行。#id 省略时默认是 fig-<num>。

![OINK 发布注记页面](/images/releasenote.webp)
{#book-release-note num="2-1" caption="发布注记页面同时是发布事实的唯一来源。" width=600 height=300}

原生图形态要求站点设置 markup.goldmark.parser.wrapStandAloneImageWithinParagraph: false，否则属性行会挂到段落上被忽略。替代文字取自 Markdown 图片本身，不会被题注替代。

表

管道表后面跟属性行，默认 ID 是 tbl-<num>。

| 隔离级别 | 脏读 | 不可重复读 | 幻读 |
| --- | --- | --- | --- |
| Read Committed | 不可能 | 可能 | 可能 |
| Repeatable Read | 不可能 | 不可能 | 可能 |
| Serializable | 不可能 | 不可能 | 不可能 |
{#tbl-2-1 num="2-1" caption="PostgreSQL 各隔离级别下的异常现象。"}

式

$$ 块后面跟属性行，默认 ID 是 eq-<num>。编号与题注排在公式右侧的同一行里，不换行；题注写长了会挤压公式那一列，公式随之变成需要横向滚动的区域。公式的题注要短。

$$
A = \frac{\mathrm{MTBF}}{\mathrm{MTBF} + \mathrm{MTTR}}
$$
{#eq-2-1 num="2-1" caption="可用性与平均故障间隔、平均恢复时间的关系。"}

原生形态依赖站点开启 Goldmark passthrough。未开启时用下面的 eq shortcode，它走本地服务端 KaTeX。

例

代码围栏加 num= 与 caption= 即编号例，默认 ID 是 eg-<num>。围栏里写的 #id 命名外层 <figure>，即引用目标，不是代码块本身。例的题注必填：只写 num 或只写 caption 都会让构建失败。编号例渲染成一个整体：题注是框的表头，正文在框内；正文恰好是一个代码块时贴着框排，不再另画一圈边框。

```sql {num="2-1" caption="按天统计主库写入量。" #eg-2-1}
SELECT date_trunc('day', ts) AS day, count(*)
FROM pg_stat_statements_history
GROUP BY 1 ORDER BY 1 DESC LIMIT 7;
```

SELECT date_trunc('day', ts) AS day, count(*)
FROM pg_stat_statements_history
GROUP BY 1 ORDER BY 1 DESC LIMIT 7;

编号：shortcode 形态

四个 shortcode fig tbl eq eg 渲染出与原生形态一致的 <figure>，注册到同一个目标表，按源码位置排序。仅在原生形态做不到时使用：图片要外链跳转、表格要在一个编号下放多张表、站点未开 passthrough、例子体是多个围栏加说明文字。

fig 用 src=（也接受内部 Markdown 内容，二者互斥），并额外支持 link alt width height class 与迁移用的 title 别名：

{{< fig num="2-2" src="/images/docsy.webp" alt="Docsy 主题的默认外壳"
    caption="OINK 的上游：Docsy 的内容模型仍在下面。" width="600" height="300" />}}

tbl 把标签、表格、题注与锚点包进一个语义 figure：

{{< tbl num="2-2" caption="四种输出下编号组件的形态。" >}}
| 输出 | 标签 | 锚点 |
| --- | --- | --- |
| HTML | 可见 | 稳定 |
| 打印 | 可见 | 稳定 |
{{< /tbl >}}

eq 的内容交给本地服务端 KaTeX，因此不依赖 passthrough：

{{< eq num="2-2" caption="连接池饱和度。" >}}U = \frac{\lambda}{\mu \cdot c}{{< /eq >}}

不带参数的 {{< eq >}} 是无编号的块级公式兜底：不注册目标，不能被 xref 引用，也不出现在公式索引里。

eg 是包装型 shortcode，正文按页面的 Markdown 策略渲染，通常装一个或多个围栏：

{{< eg num="2-2" caption="用 pg_basebackup 拉起一个新从库。" >}}
```bash
pg_basebackup -h primary -U replicator -D /pg/data -Fp -Xs -P -R
```
{{< /eg >}}

pg_basebackup -h primary -U replicator -D /pg/data -Fp -Xs -P -R

同一页里 ID 必须唯一，同一类里一个编号也只能对应一个 ID。重复时构建失败，报错指出先占用它的那一处在哪行。

交叉引用

引用同页目标可以用普通 Markdown 链接：表 2-1 指向上面那张隔离级别表。代价是标签与编号手写，改编号时需要自己检索。

xref 把标签、编号与锚点合成一处，并支持跨页与跨语言：

参见 {{< xref fig="2-2" />}} 与 {{< xref eg="2-1" />}}；
显式锚点：{{< xref fig="2-1" anchor="book-release-note" />}}。

参见 图 2-2 与 示例 2-1； 显式锚点：图 2-1。

规则：

• 最多一个类型键（fig tbl eq eg）。类型提供本地化标签（图 / 表 / 公式 / 示例）并推导出默认锚点 <kind>-<num>。
• anchor= 覆盖推导出的锚点，用于目标写了显式 #id 的情况。
• page= 跨页引用，走 Hugo 当前语言的页面查找，源码里不必硬编码 /zh/ 前缀。
• 不给类型时必须同时给 anchor= 和内部链接文字：{{< xref page="../ch01/install" anchor="sync-replication" >}}同步复制{{< /xref >}}。
• 引用可以出现在目标之前，渲染时不读注册表，因此前向引用合法。

跨页的普通 Markdown 链接在整本打印里仍然是站点 URL。需要在聚合文档里也能跳转的引用写成 xref。

索引：目录与图表清单

五个索引 shortcode 遍历同一棵书树，触发后代内容并聚合注册结果。它们通常放在书首页（_index.md）或专门的「插图目录」页上。

{{< book-toc depth=3 >}}

## 插图目录 {#lof}
{{< book-figures >}}

## 表格目录 {#lot}
{{< book-tables >}}

## 公式索引 {#loe}
{{< book-equations >}}

## 示例索引 {#lox}
{{< book-examples >}}

这五个 shortcode 在本页只给源码。它们从当前页所在的导航根向下遍历，放在一棵普通文档树里会把整棵 docs 树当作书列出。真实效果见《使用 OINK 创作优美的内容》，源码位于 content/book/_index.md。

• book-toc 的 depth 取 1–3：1 列章，2 加入嵌套分区，3 再投射每页的标题树；drafts=false 只把 book_status: draft 的行从这份生成列表里滤掉，不影响页面发布。
• book-figures / book-tables / book-equations / book-examples 不接受任何参数，各列一类，条目形如「图 2-1 — 题注」并链到稳定 ID。
• 整本打印时，这些链接全部变成文档内片段。

顺序阅读与草稿

翻页器默认对 docs、book、blog 三种类型开启，顺序是侧栏那棵树的前序遍历：分区首页在前，子页按 weight。关闭整类改 params.ui.pager_types，关闭单页写 pager: false。

params:
  ui:
    pager_types: [docs, book]

toc_hide、manual_link 纯链接占位、sidebar_divider 分隔行都不会成为翻页目的地。

草稿章节除了侧栏上的「草稿」标签，还可以开启页首横幅：

params:
  ui:
    book_draft_banner: true

横幅只在 type: book 且 book_status: draft 的页面出现，文案来自本地化键 book_draft_notice。

打印整本

书根有了 print 输出后，按可见的阅读顺序生成封面、本地目录、根页面正文与每个后代章节，全部装在一个 HTML 文档里。no_print: true 的页面、纯链接节点、分隔行与隐藏占位不会成为章节。

聚合文档里，编号组件的 ID 逐字节保留。页面内的 Markdown 标题 ID 会加上来源页面前缀，避免多章共有 summary 这类锚点时冲突，生成的标题链接同步改写。产物是面向打印的 HTML，PDF 与 EPUB 由站点自行处理。

具体开关与整章打印见打印支持。

迁移既有书稿

已有的中文书稿通常用站点自己的 figure shortcode、加粗的假题注、指向 #fig_* 的裸链接来表示图表编号。主题仓库带一个迁移脚本，把这些旧形态改写成 fig、tbl 与 xref，并保留原有的公开锚点。站点先固定到一个包含 Book 组件的已发布 OINK 版本，再迁移内容。

python3 ~/pgsty/oink/bin/migrations/book_figures.py \
  --profile tpme \
  --root /path/to/your-book \
  --report /tmp/book-migrate.json > /tmp/book-migrate.diff

四个配方对应三份真实书稿的旧约定（DDIA 的 v1 与 v2 各一个），只识别在那些书稿里观测到的形态：

diff 走标准输出，摘要走标准错误，报告含 files_scanned、files_changed、counts、skipped、idempotent 五项。脚本只改写能唯一确定的目标：无法确定编号、题注不唯一、标记形态不认识的地方原样保留，逐条记进 skipped 供人工处理。旧题注里的粗体、行内代码与公式会降级为纯文本，因为 Book 的题注契约是纯文本。

审阅 diff 之后在专用分支上应用，再运行第二遍确认幂等：

python3 ~/pgsty/oink/bin/migrations/book_figures.py \
  --profile tpme --root /path/to/your-book --write \
  --report /tmp/book-migrate-written.json

python3 ~/pgsty/oink/bin/migrations/book_figures.py \
  --profile tpme --root /path/to/your-book --no-diff \
  --report /tmp/book-migrate-second.json

第二份报告应当是 files_changed: 0、counts 为空、idempotent: true；脚本以退出码 0 表示幂等。

配方只识别这三份书稿里实际观测到的旧形态；书稿的旧约定不在这四个配方之内时，脚本不适用，需要按编号：原生形态手工改写。主题仓库的 bin/check-book-migrations.py 用干跑与幂等两项检查覆盖这四个配方。

验证

1. 构建零告警：hugo --printPathWarnings --panicOnWarning。编号写错、ID 重复、题注缺失都在这一步失败。
2. 页面上应看到「图 2-1」这样的本地化标签、可点的 xref 链接，以及点击后正确跳转的锚点。
3. 对比侧栏、翻页器、book-toc 与整本打印四处的章节顺序是否一致。
4. 检查 Markdown 输出：curl -s http://localhost:1313/zh/handbook/ch02/index.md。shortcode 形态应退化成 **图 2-2.** 题注 加原始正文，原生形态原样保留源码块与属性行。
5. 从主题仓库对构建产物跑一遍锚点检查：

python3 ~/pgsty/oink/bin/check-book.py --site-public public

它校验每个引用的目标锚点存在、类型与编号匹配、页内 ID 唯一，以及编号图片有与题注相称的替代文字。

Book shortcode 参数

xref：

book-toc：

book-figures、book-tables、book-equations、book-examples 不接受任何参数。

限制与常见问题

• 没有自动编号。章节号、图号、表号都手写；改编号是一次有意的编辑，不是构建的副作用。
• 属性行必须紧贴块，中间不能有空行。被 Prettier 之类工具移动过的属性行静默失效，图退化成普通图片。
• book_kind 与 book_part 是契约认可的元数据键，当前主题模板不渲染它们；有视觉效果的是 book_number 与 book_status。
• 索引 shortcode 会触发后代内容渲染，在超大树上明显拉长构建时间。整本 print 需要显式开启也是同一原因。
• shortcode 的正文里不能出现脚注引用，构建失败并指出改用原生形态；见上文编号：shortcode 形态。
• 主题只到打印 HTML 为止：分页、字体嵌入、索引编制、PDF / EPUB 打包都在契约之外。

相关

• 组织内容 — 目录树怎么变成侧栏与阅读顺序
• 图片 — 图注、尺寸、缩放与图片处理
• 表格 — 表格属性行与全宽表
• 公式 — KaTeX 与 passthrough 配置
• 打印支持 — 整章与整本打印

6 - 发布与下载页

OINK 把发布事实集中在两处本地数据：页面 front matter 的 release_url 指明这一页对应哪个 GitHub 发布，data/download/<key>.yaml 记录安装方式。发布卡片、资产表、下载区块与索引页都从这两处推导。构建期不访问 GitHub，也不声称某个标签或资产已经存在。

组件与事实来源

页面拥有发布事实

发布页 front matter 里的一个键就是全部记录——精确到标签的 GitHub 发布 URL：

release_url: https://github.com/pgsty/oink/releases/tag/v0.4.0

owner、项目名与标签从 URL 里解析出来，日期用页面自己的 date。不是精确 标签形式的 GitHub 发布 URL 会警告并跳过发布区块——--panicOnWarning 构建 随之失败。0.5 的 release 映射（product / version / repo / tag / date / prev / checksums）及其字符串简写已移除；仍携带它的页面会收到指名 release_url 的警告。

在需要摘要的位置放一个不带参数的 shortcode，调用里不接受任何事实：

{{< release-card >}}

卡片带着仅凭 URL 就能推导的四个链接——发布页、两种源码归档、仓库——全部本地推导。校验和文件放在正文下方的资产表里，版本对比在 GitHub 上看。

发布索引页

一个分区可以改用发布索引布局。它列出小节里的每一个常规页面，从新到旧 ——按页面日期排序，同一天内以标签里的版本号决胜（SemVer 优先级，非 SemVer 标签用确定的字典序兜底）：

---
title: 版本发布
layout: releases
---

release_url 可解析的条目读作「项目名 + 标签」——如 oink v0.4.0——下一行 是页面描述；没有它的页面保留自己的标题，版本之间夹一篇普通短文是合法条目， 不是警告。0.5 的 release_products 过滤与 release_group_by_product 分组 已移除；写了会警告。

本站的版本发布目前用普通博客列表。需要严格时间序时改用 layout: releases。

校验和资产

checksums 围栏是校验和表的原生形态，围栏里写 sha*sum 命令的原样输出：

```checksums
1e2f4c8a9d05b7361f8ac25d0e7b4913a6c8df215047eb9c3a1d6b8250f9e7c4  oink-0.4.0-linux-amd64.tar.gz
7b3d9e0c145a8f26d0b7e93c48156aa2f0d9c7b31e846a5029df1b6c7a3e8250 *oink-0.4.0-darwin-arm64.tar.gz
```

只接受两种行：<十六进制><两个空格><文件名> 与 <十六进制><空格>*<文件名>。空行与以 # 开头的行忽略。哈希长度决定算法（MD5 / SHA-1 / SHA-256 / SHA-512），一个块里只能有一种算法。格式错误的行带着行号让构建失败。文件名必须是单个路径段。类型、操作系统与架构徽章由文件名推断，属于装饰，推断不出时不显示。

资产链接的基址：页面有 release_url front matter 时推导为 https://github.com/<repo>/releases/download/<tag>/；没有发布事实的页面必须显式写 base=。两者同时存在时报错。

```checksums {base="https://repo.pigsty.io/oink/v0.4.0/" algo="sha256"}
1e2f4c8a9d05b7361f8ac25d0e7b4913a6c8df215047eb9c3a1d6b8250f9e7c4  oink-0.4.0-linux-amd64.tar.gz
```

release-assets 是同一个解析器与渲染器的 shortcode 形态。它多一个围栏没有的 src=，可以把校验和文件本身提交为页面资源或全局资产（src 与围栏内容互斥）；group="auto" 按平台与架构分组：

{{< release-assets group="auto" >}}
5a0c7d1e93b4826f0ad35c9e17b6402d8f1c95ae63d70b28c4e19a5f38207db6  oink-0.4.0-1.el9.x86_64.rpm
c93f16a8d052b7e41ac68d3907b25fe0a41d8c7362b95e0187ac4d63f9520ea8  oink-0.4.0-1.el9.aarch64.rpm
{{< /release-assets >}}

HTML 里哈希截断显示，完整哈希保留在无障碍名称与复制源里，复制按钮由按需加载的本地运行时提供。禁用 JavaScript 时仍是一张完整的带链接表格。打印展开完整哈希且不带控件，Markdown 与 RSS 是完整哈希的管道表。

下载渠道数据

安装方式属于产品，不属于某一次发布，因此存放在 data/download/<key>.yaml。本站真实的记录是 data/download/prd5.yaml：

version: 0.4.0
repo: pgsty/oink
published: true
channels:
  - id: script
    kind: rolling
    title: Install script
    title_zh: 安装脚本
    icon: fa-solid fa-bolt
    note: The rolling channel deliberately contains no version interpolation.
    note_zh: 滚动渠道刻意不插入版本号。
    steps:
      - title: Install
        title_zh: 安装
        code: curl -fsSL https://repo.example.org/oink/install | bash
        lang: bash
  - id: source
    kind: pinned
    title: Source archive
    title_zh: 源码归档
    icon: fa-solid fa-code-branch
    url: https://github.com/pgsty/oink/archive/refs/tags/${tag}.tar.gz
    steps:
      - title: Clone the tag
        title_zh: 克隆标签
        code: git clone --branch ${tag} https://github.com/pgsty/oink.git
        lang: bash
  - id: assets
    kind: pinned
    title: Release assets
    title_zh: 发布资产
    icon: fa-solid fa-box-open
    checksums: |
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa  oink-0.4.0.tar.gz

记录级字段只有 version repo tag published channels 五个，多写一个键即构建失败。version 也可以不写在这里，改由站点的 params.version 提供。

每个渠道：

两条规则：

• 本地化按后缀解析：<字段>_<精确语言> → <字段>_<主语言> → <字段>。中文站解析 title_zh_cn、title_zh、title。不接受 camelCase 别名。
• 只有固定版本渠道的 url 与 steps[].code 能插值 ${version} 与 ${tag}。滚动渠道拒绝插值，避免稳定版安装命令被绑定到某个版本。标题与说明不插值。

渲染下载区块

download 接受恰好一个位置参数，即数据键：

{{< download "prd5" >}}

curl -fsSL https://repo.example.org/oink/install | bash

git clone --branch v0.4.0 https://github.com/pgsty/oink.git

HTML 渲染一排锚点 chip 加各渠道分区，代码步骤复用增强代码块与按需加载的复制运行时，校验和渠道复用上面那张资产表。打印静态展开同样的内容，Markdown 输出标题、源码围栏与完整哈希，RSS 不输出这个组件。

标签未打、资产未上传时，把记录标为未发布：

published: false

滚动渠道照常可用。固定版本渠道变成不可点击的「待发布」状态，省略固定版本命令，禁用资产链接与复制控件。标签与资产可解析之后再翻转这个开关，不要先在正文里写入推测出来的链接。

同一份记录也能被 Landing 页面的 download 分区消费，不需要第二套版本模型，见首页与落地页。

与博客发布注记的关系

两者分工：

• 博客里的发布注记（本站在 content/blog/release/）是叙事：这一版改了什么、怎么升级、有什么破坏性变更。它的 front matter 里带 release_url，页首可以放一张 release-card。写法见博客与文章。
• 下载数据是操作：选哪个渠道、运行哪条命令、校验哪个哈希。它与版本号解耦，升级时只改一处。

一次发布的顺序：更新 data/download/<key>.yaml 的 version → 新写一篇 content/blog/release/<version>.md 并填 release_url → 标签与资产就绪后把 published 翻成 true。

验证

1. 构建零告警：hugo --printPathWarnings --panicOnWarning。哈希行格式、算法混用、缺 base、渠道字段拼错都在这一步失败。
2. 页面上：卡片显示的标签与日期与仓库一致；资产表每行都能点开真实的下载 URL。
3. 逐条核对哈希与实际产物：组件只负责排版，不验证内容。
4. 检查非 HTML 输出里哈希是完整的：

curl -s http://localhost:1313/zh/docs/write/releases/index.md | grep -c '^| '

5. 发布前先用 published: false 走一遍，标签与资产确实存在后再改成 true；每种语言、子路径部署各测一次。

相关

• 博客与文章 — 发布注记住在哪、怎么排
• 代码块 — 下载步骤里的代码渲染与复制
• 首页与落地页 — Landing 的 download 分区
• 配置总览 — params.version 与相关站点参数
• 版本升级 — 消费站怎么跟随主题版本

7 - API 文档

一页接口文档由一份 OpenAPI 规范加一个 shortcode 构成。Swagger UI 与 Redoc 两个运行时随主题分发（版本分别是 5.32.13 与 2.5.3，见仓库 VENDOR.json），页面用到才加载，构建与浏览都不访问外部服务。

三个步骤：把规范文件放进 static/，新建一页写上 shortcode，需要专用外壳时把页面 type 改成 swagger。

规范文件的位置

规范文件放在 static/ 下，原样发布到站点根，两个 shortcode 得到的都是浏览器可取的 URL：

不要把规范文件放在页面旁边。redoc 会在内容目录里查找同名文件并据此拼出 URL，但内容目录里的 .yaml 是页面资源，Hugo 只在它被引用或处理时才发布。redoc 只拼 URL、不引用资源，浏览器因此得到 404。

远程规范（https://… 开头）两个 shortcode 都接受，但那是一项网络依赖，还会把读者的元数据暴露给那台主机。内网部署与有 CSP 的站点应当使用同源规范。

下面的例子用真实存在的 /openapi/docs-demo.yaml，一份演示用的集群管理 API，没有可访问的服务端。

Swagger UI

swagger 只有一个具名参数 src，值是从站点根开始的 URL。它经过主题的 URL 校验，子路径部署同样正确：

{{< swagger src="/openapi/docs-demo.yaml" >}}

它渲染一个 class="td-swagger-ui" 的容器并就地初始化。容器 ID 由页面地址与 shortcode 序号推导（td-swagger-<hash>-<n>），因此同一页可以放多个。

本页只给源码，不真渲染 Swagger UI：它自己生成的标记有三处 axe WCAG AA 违规（服务器下拉框没有可访问名称、版本号区域是不能聚焦的可滚动区），本站的无障碍门禁要求每个页面零违规。下面的 Redoc 是真渲染的。

Redoc

redoc 只接受一个位置参数，即规范路径。多写一个参数构建失败。

{{< redoc "openapi/docs-demo.yaml" >}}

路径解析按顺序有三条分支：http 开头视为远程 URL；能在内容目录里找到同名文件时用 baseURL + 页面目录 + 文件名；否则用 baseURL + 原样路径。redoc 的路径因此不要以斜杠开头，/openapi/… 会拼出 https://example.com//openapi/… 这样的双斜杠。与 swagger 不同，它生成基于 baseURL 的绝对 URL。

主题固定了 hide-hostname hide-logo suppress-warnings lazy-rendering native-scrollbars 五个属性，并用 CSS 隐藏 Redocly 品牌图标。Redoc 的其余属性目前不开放给作者，需要它们时在站点里覆盖 layouts/_shortcodes/redoc.html。

专用页面外壳

接口文档页通常较宽较长，可以用 swagger 页面类型：

---
title: 集群管理 API
type: swagger
page_width: wide
cascade:
  type: swagger
---

swagger 是主题默认的外壳类型之一（params.ui.shell_types 默认是 [docs, book, blog, swagger]，站点覆盖这个列表时需要保留它）。它与 docs 外壳的差别只有两处：<body> 上多一个 td-swagger class 供样式挂钩，以及不显示版本横幅。侧栏、目录、面包屑、翻页器与页尾都照常。

外壳与页宽的完整说明见布局与页面类型。

输出形态

接口文档只在 HTML 里有内容。要让打印或 Agent 输出里也有接口信息，在同一页用正文写关键端点的说明；shortcode 之外的正文在四种输出里都完整保留。

限制与常见问题

• 两个组件的容器 ID 都按「页面地址 + shortcode 序号」推导，同一页放多个互不冲突。
• 两者可以同页共存，但页面会很长，也会同时加载两套运行时。正式站点选一个。
• Swagger UI 的标记有 axe WCAG AA 违规（select-name、scrollable-region-focusable），它来自上游产物，主题不改写。站点若有零违规的无障碍门禁，把这类页面排除，或改用 Redoc。
• redoc 不接受额外属性参数：写第二个位置参数构建失败。
• redoc 路径不要以 / 开头，否则拼出双斜杠。
• 规范文件必须能被浏览器取到：放 static/，构建后确认 public/ 下存在该文件。
• 没有服务端 mock：Swagger UI 的 “Try it out” 会向 servers 里写的地址发起真实请求，示例规范里的地址不可访问。

验证

1. 构建零告警：hugo --printPathWarnings --panicOnWarning。
2. 规范确实发布了：ls public/openapi/docs-demo.yaml，或访问 http://localhost:1313/openapi/docs-demo.yaml。
3. 页面上能展开端点、看到 schema；浏览器控制台没有 404 或跨域报错。
4. 断网后再刷新一次：运行时是本地的，规范同源时界面应照常出现。

相关

• 编写页面 — 页面 front matter 与正文的基本写法
• 布局与页面类型 — shell_types、页宽与侧栏
• Agent 支持 — 为什么只在 HTML 里有内容的组件要配文字说明
• 代码块 — 用请求 / 响应示例代替整套 UI 的轻量做法