OINK 文档

• 1: OINK 是什么
  • 1.1: 亮点特性
  • 1.2: Case 导览
  • 1.3: 开源许可与致谢
• 2: 十分钟上手
  • 2.1: 仓库导览
  • 2.2: 从零建站与其它安装方式
• 3: 创作内容
  • 3.1: 编写页面
  • 3.2: 组织内容
  • 3.3: 页面参数
  • 3.4: 博客与文章
  • 3.5: 书籍出版
  • 3.6: 发布与下载页
  • 3.7: API 文档
• 4: 组件总览
  • 4.1: 提示块
  • 4.2: 图片
  • 4.3: 代码块
  • 4.4: 标签页
  • 4.5: 表格
  • 4.6: 参数表
  • 4.7: 步骤
  • 4.8: 卡片
  • 4.9: 文件树
  • 4.10: 公式
  • 4.11: Mermaid
  • 4.12: PlantUML
  • 4.13: 思维导图
  • 4.14: Draw.io
  • 4.15: ECharts
  • 4.16: Infographic
  • 4.17: 画廊
  • 4.18: 徽章
  • 4.19: 按键
  • 4.20: 引用
  • 4.21: Asciinema
• 5: 定制站点
  • 5.1: 配置总览
  • 5.2: 品牌外观
  • 5.3: 首页与落地页
  • 5.4: 导航与菜单
  • 5.5: 布局与页面类型
  • 5.6: 全文检索
  • 5.7: 命令面板
  • 5.8: 键盘导航
  • 5.9: 多语言
  • 5.10: 多版本
  • 5.11: 分类体系
  • 5.12: 仓库与页面信息
  • 5.13: 打印支持
  • 5.14: Agent 支持
• 6: 维护管理
  • 6.1: 本地预览
  • 6.2: 发布上线
  • 6.3: 启用评论
  • 6.4: 分析与 SEO
  • 6.5: 版本升级
  • 6.6: 排错与检查
• 7: 设计与开发
  • 7.1: 架构契约
  • 7.2: 组件契约
  • 7.3: 外壳与导航契约
  • 7.4: 落地页契约
  • 7.5: OINK 迁移边界
  • 7.6: 设计决策
    • 7.6.1: 警告与安全回退
    • 7.6.2: 配置模型
    • 7.6.3: Markdown 优先创作
  • 7.7: 设计研究
    • 7.7.1: Goldmark 块属性实测
    • 7.7.2: 消费站与迁移证据
  • 7.8: 设计提案与 PRD
    • 7.8.1: 反向链接与知识图谱
    • 7.8.2: 媒体收敛
    • 7.8.3: Agent 批量索引

1 - OINK 是什么

OINK 是一款独立的 Hugo 主题，用于搭建中大型技术文档站。它从 Docsy 演化而来：保留 Docsy 的内容模型与多语言行为，替换外壳、导航、搜索与内容组件。

消费站点的构建依赖只有一个 Hugo Extended 二进制，不需要 Node.js、npm 或 PostCSS，也不请求 CDN。Bootstrap、Font Awesome、字体、本地搜索、图表与 API 文档运行时都提交在主题仓库里，只在页面用到时下发。

组件不是另一套模板语言：> [!NOTE] 是提示块，表格加一行 {.fields} 是参数表，图片下面加 {caption=} 就有图注。当前有十四个生产站点在用它，本站是其中之一。

主题的职责

• 文档与博客外壳：导航、侧栏树、目录、面包屑、翻页、深色模式、打印视图与无障碍交互。
• 多语言框架：译文路由、缺译回退、语言权重、RTL，以及 32 个界面语言包。
• 本地运行时：Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic 与本地全文检索。
• 内容组件：提示块、标签页、步骤、卡片、参数表、文件树、画廊、徽章、按键等，多数有 Markdown 原生形态。
• 内容类型：普通文档之外，还内置书籍编号与交叉引用、发布与下载页、数据驱动的 Landing 首页、OpenAPI 文档页。

主题不负责源码托管与部署：站点可以放在 GitHub、GitLab 或私有 Git 上，Hugo 生成的静态文件可用任何托管平台发布。站点自己的内容、品牌与业务组件仍归站点管理，主题只提供通用外壳与可复用组件。

适用范围

与其它文档方案的差别

下表只列结构性差别，且只写能从各项目自身文档与仓库确认的部分。各项目的版本会变动，选型前以其当前文档为准。

两点补充。每页 Markdown 输出与 llms.txt 不是 OINK 独有的能力，Docsy 与 Hextra 也有，三者都要站点在 outputs 里显式打开。表格最后一行的三项只有 OINK 内置，它们来自 PGSTY 自己的生产站点，不是通用文档站的必需品。主题的交互功能默认关闭，搜索、缩放、评论与反馈都要站点显式打开。

OINK 不是叠在 Docsy 上的皮肤，而是 fork 之后独立演化的主题。Docsy 的源码历史、Apache-2.0 义务与署名完整保留，细节见开源许可与致谢。

入口

• 十分钟上手 — 安装 Hugo、克隆本站、替换站点信息、发布到 GitHub Pages。
• 组件总览 — 一个组件一页，先源码后效果。
• 示例站点 — 十四个生产站点，各自用了 OINK 的哪部分。

亮点特性按能力逐条列出主题提供的东西，每条链接到讲它的指南页。

1.1 - 亮点特性

本页逐条列出 OINK 与普通 Hugo 主题的差别，每条末尾给出讲它的指南页。要立即安装，见十分钟上手。

组件写在 Markdown 里

提示块是 > [!NOTE] 块引用（十种语义类型加一个中性折叠块），参数表是表格加一行 {.fields}，步骤与卡片是列表加 {.steps} / {.cards}，图注是图片下面一行 {caption="…"}。标签页是几个相邻围栏各带一个 {tab="…"}；文件树、画廊、Mermaid、ECharts 是以语言命名的数据围栏。这些写法在 GitHub 或普通 Markdown 阅读器中退化为块引用、表格、列表与代码块，内容不丢失。

29 个 shortcode 覆盖原生形态表达不了的场景：卡片带图标与图片、参数表条目正文是多段 Markdown。

→ 组件总览

只要一个 Hugo 二进制

消费站点的全部构建依赖是 Hugo Extended 0.160.1 或更新版本。SCSS 由 Hugo 内置的 Sass 转译器编译，主题不调用 postCSS；没有 npm、没有 webpack、没有构建期下载。用 Hugo Module 方式安装主题时需要本机有 Go 来解析模块，用离线归档或 submodule 则不需要。

「仅依赖 Hugo」指的是构建依赖。界面交互仍在浏览器中执行 JavaScript：搜索、命令面板、图表、标签页都是页面脚本，区别在于这些脚本随主题分发、按页面用到的功能下发。

→ 十分钟上手

本地优先

浏览器需要的资源全部提交在主题仓库里：Bootstrap、Font Awesome、四款字体、Lunr、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic。VENDOR.json 逐项记录 28 个依赖的版本、来源、许可证文件与 SHA-256 校验值，更新某个运行时要同时更新产物、许可证与校验值。

对可能引起网络请求的功能，主题让构建失败而不是静默连出去：PlantUML 缺 params.plantuml.svg_image_url、Diagrams.net 缺 params.drawio.drawio_server、Algolia 缺 appId / apiKey / indexName，构建都会报错。

本地优先不覆盖作者自己添加的内容。以下都是显式的网络选择：外部链接、远程图片与视频、iframe、远程 API 规范；Algolia、Google 自定义搜索这类托管搜索；分析、评论与其它 SaaS 集成；作者主动配置远程渲染器的 PlantUML 与 Diagrams.net。用到它们的页面仍然是有效页面，但站点不应再宣称这些页面可以完全离线使用。

→ 开源许可与致谢 · 配置总览

一份内容，四种输出

每个组件在四种输出下都有确定的形态：交互式 HTML；去掉缩放与复制控件、折叠块完全展开的打印页；纯 Markdown；RSS。打印视图按栏目整份生成（本栏目是 /zh/_print/docs/about/），Markdown 版本是同一页面地址加 index.md。

站点在 outputs 里显式选择需要哪几种，主题不替站点决定。

→ 打印支持 · Agent 支持

双语与 32 个界面语言

多语言走 Hugo 原生机制：译文路由、按权重排序的语言选择器、缺译回退、RTL、以及 canonical 与 alternate 元数据。界面文案有 32 个语言包，共用同一套 key；英语、简体中文（zh-cn 与通用 zh）与繁体中文（zh-tw）经过人工审校，其余语言保留 Docsy 继承下来的翻译，OINK 新增的键先用英文兜底。

→ 多语言

全文检索不出站

打开 params.offline_search 后，Hugo 为每种语言生成一份索引，浏览器用本地 Lunr 检索拉丁文字、用子串回退检索中日韩文本，查询内容不发给任何第三方。页面可以用 search_boost 调权重、用 search_keywords 补同义词。

→ 全文检索

命令面板

Cmd/Ctrl + K 打开命令面板；裸按 / 进入搜索态，裸按 \ 进入纯命令态。面板里同时有页面、命令与页面动作（切换语言、切换主题、复制 Markdown 等），搜索与操作共用一个入口。

→ 命令面板

键盘导航

默认开启，可按站点或按栏目关闭。w s 在侧栏树上下移动，a d 折叠展开，q e 上一篇下一篇，j k 沿页面目录跳转，t 切换深浅色，l 切换语言，h 隐藏阅读外壳。输入框、文本域获得焦点或输入法处于组字状态时，单键快捷键全部让行。页脚最底层栏的问号按钮打开速查卡。

→ 键盘导航

文档之外的四种内容

主题还内置四类需要额外结构的页面：

• 书籍：章节编号，图 / 表 / 式 / 例用 {#id num=} 编号、用 xref 交叉引用，book-toc、book-figures 一类 shortcode 生成索引，整本可打印。
• 发布与下载页：data/download/*.yaml 生成发布卡片、资产表与校验和，发布状态可控。
• Landing 首页：data/home/<lang>.yaml 拼装首页分区；任意页面加 layout: landing 也能用 data/landing/ 的数据。
• API 文档：Swagger UI 与 Redoc 都是本地运行时，spec 放站内即可。

→ 书籍出版 · 发布与下载页 · 首页与落地页 · API 文档

面向 AI 助手的输出

outputs 里加上 markdown，每个页面就多一份 .md，HTML 的 <head> 里带 rel="alternate" 指过去，页面动作里也多出「复制 Markdown」与「查看源码」。LLMS 输出格式在站点根目录生成 llms.txt 内容清单（本站是 https://oink.pgsty.com/zh/llms.txt）。

「在 ChatGPT / Claude 中打开」默认关闭：读者点击时会把当前 URL 交给第三方，需要站点显式打开 params.ui.page_context_menu.assistant_links。

→ Agent 支持

多版本

配置 params.versions 后顶栏出现版本菜单，旧版本站点顶部显示归档横幅，提示读者查看最新版本；菜单是否逐页跳转由站点决定。多个版本是分别构建、分别部署的静态站点，不需要运行时支持。

→ 多版本

自己验证

本站启用了上面多数特性，三条自查：

1. 在任意页面按 Cmd/Ctrl + K，输入 postgres 查看本地搜索结果；按 \ 进入纯命令态。
2. 在当前页面地址后加 index.md，得到这一页的 Markdown 版本。
3. 打开 https://oink.pgsty.com/zh/llms.txt，那是给 AI 助手的站点清单。

相关

• OINK 是什么 — 定位、适用场景与对比
• 示例站点 — 这些特性在生产站点里怎么用
• 十分钟上手 — 从克隆到上线
• 配置总览 — 上面提到的参数在哪查

1.2 - Case 导览

正式的 Case 案例库 把十五个生产站点整理成可复用的实现模式， 首页展示的也是同样这十五个。它们全都使用 OINK，本站本身也作为自举案例列入。

当你已经知道自己要搭建哪类站点时，可以从这里开始：先通过案例了解架构与 取舍，再沿页面链接进入具体配置文档。案例中的数量描述对应盘点时的快照， 不是对持续变化的线上站点作永久承诺。

发行版文档

pigsty.io

大型英文站，把发行版手册、博客、扩展目录、分类、版本导航与价格落地页放在 同一个站点中。

pigsty.cc

独立部署的中文对等站；当两种语言的语料都已成为完整产品时，拆成两个单语站 是一种清晰的取舍。

pgsty.pro

双语版本档案站，从可复用的结构化发布数据渲染大量版本页面。

产品文档

PIG

紧凑的双语命令行工具手册，配有数据驱动首页与体量更大的博客。

SOW

双语运维手册，使用独立下载内容类型展示发布元数据与产物。

SILO

大型上游迁移案例，通过受检查的清单生成双语文档导航。

PG Exporter

把生成导航、结构化指标目录与系统字体组合起来的指标手册。

书籍

《设计数据密集型应用》

多语言、多版本书籍，也是编号图表、交叉引用、章节导航与索引最完整的案例。

《The Product-Minded Engineer》

只需要 OINK Book 外壳的聚焦型双语出版物。

《PG 技术内幕》

已完稿的中文译本，刻意做成单语 Book：没有文档树，也没有可切换的第二语言。

汇编、落地页与自定义站点

pgsql.cc

聚合型运维文库，让多个上游手册与完成度不一的翻译树共享搜索和视觉体系。

pgsty.com

小型双语公司站，展示 OINK 也可以主要作为数据驱动的落地页系统。

Capslock

每种语言只有两页，其中自定义外壳承载数据驱动交互配置生成器。

oink.pgsty.com

完整参考站：公开文档、实时组件示例、设计契约、多种内容外壳与回归覆盖都在 同一个仓库中。

pgext.cloud

PostgreSQL 扩展目录：把可检索的数据集作为站点主体呈现，收录 2,241 个扩展、 576 个已打包版本，覆盖 16 个 Linux 平台。

如何选择起点

• 常规产品手册：从 PIG 或 SOW 开始。
• 大型迁移：对比 SILO 与 pgsql.cc。
• 书籍：对比精简的 TPME 与更复杂的 DDIA， 单语场景可参考 《PG 技术内幕》。
• 落地页或交互站：参考 pgsty.com 或 Capslock。
• 最完整的参考实现：使用 OINK Docs。
• 如果读者是来查询数据集而不是来阅读的，看看 ext.pgsty.com 如何把数据集作为站点主体呈现。

主题仓库的 tests/site/ 是内部 CI 夹具，而不是起步模板；其中页面的职责是 触发渲染行为。上面的生产案例更适合作为架构与设计参考。

→ 浏览全部案例 · 十分钟上手 · 仓库导览

1.3 - 开源许可与致谢

OINK 由三层材料组成：主题源码、文档内容、随主题分发的第三方资源。三者各自的许可证不会被重新授权成一份统一作品。下面每张表都指向仓库里的权威文件，摘要与许可证原文不一致时以文件为准。

许可证对应关系

两条边界要分清：CC BY 4.0 只覆盖原创文档内容，不覆盖主题代码、商标、截图与第三方资源；主题采用 Apache-2.0，也不会把随附依赖变成 Apache 许可的作品。

上游：Docsy

主题 NOTICE 记录的事实：

• OINK 派生自 Docsy，Copyright 2018 Google LLC and Docsy contributors。
• OINK 自身的主题工作 Copyright 2026 PGSTY contributors。
• 项目与上游同为 Apache License 2.0；第三方浏览器依赖的许可、来源、版本与校验值记录在 VENDOR.json，各自要求的 NOTICE 文件与对应资源放在一起分发。
• Docsy 名称与 Google 商标归各自权利人所有，此处引用只用于标识上游项目，不表示背书。

本站也派生自 Docsy 项目网站，这段渊源记录在站点自己的 NOTICE 里。Docsy 是 OINK 唯一的代码上游：源码历史、Apache-2.0 义务与版权声明完整保留，按 Apache-2.0 的要求，修改过的文件需要标注。

随主题分发的第三方运行时

主题把浏览器要用的资源全部提交在仓库里（assets/third_party/、assets/js/third_party/、static/webfonts/），消费站点不需要 npm，也不会在构建期下载任何东西。VENDOR.json 是这批资源的机器可读清单，逐项记录名称、固定版本、来源 URL、许可证文件路径，以及每个选取产物的 SHA-256；清单里还有三棵资源目录的整体校验值。

下表是清单快照（VENDOR.json 生成于 2026-08-17，schema 1，共 26 项）。版本会随主题发布变动，以仓库里的 VENDOR.json 为准。全部来源都是 npm registry（https://registry.npmjs.org/…）。

许可证原文与各资源放在一起：例如 assets/third_party/bootstrap/LICENSE、assets/third_party/katex/LICENSE；Swagger UI、Redoc 与 ECharts 还随包带了各自的 NOTICE 或打包声明文件。Lunr 是唯一的例外，代码在 assets/js/third_party/，许可证在 assets/third_party/lunr/LICENSE。

再分发主题时，这些许可与声明材料必须一并保留。更新某个运行时意味着在同一次变更里同时更新产物、许可证文件、来源与校验值。

字体与图标

三款字体（Inter、Chakra Petch、IBM Plex Mono）都采用 SIL Open Font License 1.1，字体文件提交在 static/webfonts/：Inter 十四个子集文件、品牌字体四个，加上 Font Awesome 的三个，共二十一个。Font Awesome Free 7.3.1 是复合许可：图标图形 CC BY 4.0、字体文件 SIL OFL 1.1、代码 MIT，原文在 assets/third_party/Font-Awesome/LICENSE.txt。

主题不向远程字体服务发请求：仓库里没有 Google Fonts 之类的外链，字体一律由站点自身 baseURL 下发。更换字体或改用系统字体栈见品牌外观。

设计参考

代码上游只有 Docsy 一个。下面这些项目是设计语言上的参考，既不是代码来源也不是运行时依赖，OINK 没有移植它们的代码：

Hugo 是构建平台，Go 在 Hugo Module 安装方式下负责解析模块。两者都是前提条件，主题不重新分发它们的可执行文件。

引用这些名字用于说明传承、依赖或灵感来源，不表示相关项目为 OINK 背书；各项目与产品名称归其权利人所有。

复用这份文档

CC BY 4.0 允许任何目的的分享与演绎，条件是给出署名、提供许可证链接、说明是否做过修改，并且不得暗示 OINK、PGSTY 或上游项目为改编内容背书。一段合格的署名可以是：

本文改编自 PGSTY 贡献者编写的 OINK 文档，采用 CC BY 4.0 许可，并做了修改。

页面里单独署名的图片或引文，要保留它们各自的署名与许可；删掉页脚不会免除署名义务。

复用这个主题

Apache-2.0 允许按条款使用、修改与分发主题源码及编译产物，条件是保留许可证、版权与归属声明，保留 NOTICE 内容，并在分发修改后的源码时标明改过哪些文件。主题发行包应当包含 LICENSE、NOTICE、VENDOR.json，以及清单引用的全部第三方许可证文件。

Apache-2.0 不授予商标使用权，也不会把第三方资源变成 Apache 许可的作品。

相关

• OINK 是什么 — 项目定位与来历
• 亮点特性 — 本地优先具体指什么
• 配置总览 — 哪些功能会引入外部服务
• 品牌外观 — 换字体与图标

2 - 十分钟上手

这条路径不从空目录开始，而是克隆你正在读的这个站点，删掉不需要的部分，再替换成你自己的信息。本站是 OINK 的回归站，包含每个组件与每种页面类型，并与主题保持同版本；从它开始删减，比从空目录逐项补配置与示例少写很多。

前提：一台能安装 Hugo Extended 与 Go 的机器、一个 GitHub 账号、十分钟。不需要 Node.js，也不需要其它前端工具链。

结果

完成后得到一个双语文档站：左侧栏是你的目录树，右侧是本页目录，顶栏有全文搜索与命令面板，深浅色跟随系统；一份 Markdown 同时产出网页、打印页、纯 Markdown 与 RSS；托管在 GitHub Pages 上。

步骤

1. 安装 Hugo Extended 与 Go

   除 Git 之外需要两样。Hugo Extended 必须是 0.160.1 或更高版本：标准版 Hugo 没有内置 Sass 编译器，编译不了主题样式，构建失败。Go 用于解析模块：OINK 以 Hugo Module 发布，Hugo 通过 Go 的模块机制下载并校验 github.com/pgsty/oink。

   macOS

   brew install hugo go git

   Linux

   # 发行版仓库里的 Hugo 往往过旧，改用官方 deb 包（本站 CI 也是如此）
   curl -LO https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.deb
   sudo dpkg -i hugo_extended_0.164.0_linux-amd64.deb
   sudo apt install -y golang-go git

   Windows

   winget install Hugo.Hugo.Extended
   winget install GoLang.Go
   winget install Git.Git

   安装完成后核对一次，输出里必须出现 extended：

   $ hugo version
   hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z
   $ go version
   go version go1.26.6 darwin/arm64
   

   其它平台按 Hugo 安装指南 与 go.dev/dl 安装，注意选 extended 版本。

2. 克隆文档站并预览

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

   打开 http://localhost:1313/，中文站在 http://localhost:1313/zh/。第一次启动会下载主题模块（几秒到一分钟，取决于网络），之后修改文件是毫秒级热重载。

   已提交的 go.mod 固定了主题版本，克隆之后即可构建，不需要额外的安装脚本。

   说明

   仓库里的 Makefile 只是几条命令的别名。make dev 与 make check 通过 HUGO_MODULE_REPLACEMENTS 使用同级的 ../oink 主题 checkout；make build 与 make serve 始终使用 go.mod 固定的公开版本。新站点用 hugo server 即可。

3. 替换站点信息

   站点身份：全部在 hugo.yml 里。baseURL 用的是 YAML 锚点，实际地址写在 params.productionURL 上，只改这一处：

   hugo.yml

   title: Product Docs # 顶栏站名与 <title>
   
   params:
     productionURL: &productionURL https://docs.example.com/
     github_repo: https://github.com/example/product-docs # 「编辑当前页面」指向哪
     copyright:
       authors: '[Example Inc.](https://example.com/)'
       from_year: 2026
     footer_center_info: ''
   
   baseURL: *productionURL

   languages.en.title 与 languages.zh.title 会覆盖顶层 title，两处一起改。参数逐项的含义与默认值见配置总览。

   删掉本站专用的配置：保留它们会让你的站点指向 OINK 的仓库与账号。

   hugo.yml 里的键	怎么处理
   services.googleAnalytics.id	OINK 的统计 ID，删掉；需要统计时换成你自己的
   params.comments	giscus 指向 pgsty/oink.pgsty.com 的讨论区，整段删掉或换成你的仓库
   params.tdVersion params.version params.version_menu params.versions	OINK 的版本菜单，删掉
   params.github_project_repo	主题仓库链接，删掉
   languages.<lang>.menus.main	顶栏菜单指向 /docs/tutorial 这类本站栏目，按你的目录重写

   换 Logo 与图标：替换这三个文件，文件名保持不变，主题按文件名挂载：

   static/

   static/favicon.svg           # 浏览器标签页图标
   static/favicon.ico
   static/apple-touch-icon.png  # iOS 添加到主屏

   static/logo.svg 是本站自己的品牌组合标，没有参数指向它：删掉，或者换成你的横向字标再设 params.wordmark。

   替换内容：content/docs/ 是 OINK 自己的主题文档，整棵删除，写你自己的第一页：

   rm -rf content/docs && mkdir -p content/docs

   content/docs/_index.md

   ---
   title: Docs
   linkTitle: Docs
   description: Product documentation.
   weight: 20
   ---
   
   Everything about running Product in production.

   content/blog/ 可以留一篇当模板，也可以整个目录删除（删除后把 menus.main 里的 blog 项一并删掉）。哪些目录必须保留、哪些是文档站自用，见仓库导览。

   只做英文站：删除 languages.zh 整段与所有 .zh.md 文件，languages 缩成一段：

   hugo.yml

   defaultContentLanguage: en
   languages:
     en:
       label: English
       locale: en-US
       weight: 1
       title: Product Docs
       menus:
         main:
           - { name: Docs, pageRef: /docs, weight: 20 }

   find content -name '*.zh.md' -delete

   保留双语或换成其它语言对，见多语言。

4. 部署

   在 GitHub 上新建一个空仓库，把本地历史换成你自己的：

   rm -rf .git && git init -b main
   git add . && git commit -m "Initial documentation site"
   git remote add origin git@github.com:example/product-docs.git
   git push -u origin main

   仓库自带 .github/workflows/pages.yml：推到 main 分支即构建并发布，也可以在 Actions 页面手动触发（workflow_dispatch）。它固定 Hugo Extended 与 Go 的版本，用 --printPathWarnings --panicOnWarning 构建，baseURL 由 GitHub Pages 提供，因此发布到 example.github.io/product-docs/ 这类子路径也不必改配置。

   在仓库的 Settings → Pages → Build and deployment → Source 选 GitHub Actions。默认值是 Deploy from a branch，不改这一项 workflow 会在部署步骤失败。

   删除 scripts/ 后要改 workflow

   pages.yml 中的 Verify advertised and pinned release match 一步运行 node scripts/check-release-pin.mjs，校验站点公告的版本与 go.mod 固定的版本一致。删掉 scripts/ 之后，把这一步与 Set up Node.js 一并从 pages.yml 移除。

   Cloudflare Pages、Netlify、Nginx 与离线打包见发布上线：构建命令都是 hugo --gc --minify，区别只在 baseURL 与环境变量。

验证

本地运行一次生产构建。它比开发服务器严格，路径告警会让构建失败：

hugo --gc --minify --printPathWarnings --panicOnWarning

输出 Total in … 且没有 WARN / ERROR 即通过。再对照预览核对：

• 顶栏是你的站名与 Logo，浏览器标签页是你的 favicon
• 侧栏是你自己的目录树，每页都能打开
• 按 Ctrl+ 加 K（macOS 上是 ⌘+ 加 K）打开命令面板，能搜到刚写的页面
• 页面标题右侧的菜单里，「编辑当前页面」指向你自己的仓库，不是 pgsty/oink.pgsty.com
• 部署后 GitHub 仓库 Actions 页面里的 Deploy Oink site to GitHub Pages 是绿的

构建报错见排错与检查。

下一步

• 仓库导览 — 克隆下来的每个目录是什么，哪些可以删。
• 编写页面 — 一页文档的组成：front matter、标题锚点、链接与图片。
• 组件总览 — 提示块、标签页、参数表、文件树等，每个组件一页。
• 品牌外观 — 主色、字体预设、页宽与自定义样式。
• 发布上线 — GitHub Pages 之外的托管方式与验收清单。

给编码助手的指令

上面四步可以交给编码助手（Claude Code、Codex 等）执行。复制下面这段指令，把方括号里的三处替换为你自己的信息：

请帮我用 OINK 主题建一个文档站，按下面的流程做，遇到不确定的地方按「只在缺信息时问人」处理。

1. 检查环境：运行 `hugo version`，要求输出包含 `extended` 且版本 >= 0.160.1；运行 `go version`，
   要求能拿到版本号。任一不满足就先按官方文档安装，macOS 用 `brew install hugo go`，
   Debian/Ubuntu 装 GitHub Releases 上的 hugo_extended deb 包。
2. 克隆站点模板：`git clone https://github.com/pgsty/oink.pgsty.com [目标目录]` 并进入该目录。
3. 改 hugo.yml 三处：顶层 `title` 与 `languages.<lang>.title` 改成 [站点名称]；
   `params.productionURL` 改成 [站点域名]（baseURL 是指向它的 YAML 锚点，不要单独改 baseURL）；
   `params.github_repo` 改成本站将来的仓库地址。
   同时删掉这些本站专用配置：`services.googleAnalytics`、`params.comments`、
   `params.tdVersion`、`params.version`、`params.version_menu`、`params.versions`、
   `params.github_project_repo`，并把 `menus.main` 改成只指向 /docs 与 /blog。
4. 清空示例内容：删除 `content/docs/` 整棵目录，新建 `content/docs/_index.md`
   （front matter 至少有 title / description / weight）；`content/blog/` 下只保留一篇文章当模板。
   删除文档站自用的脚手架：`tests/`、`scripts/`、`playwright.config.mjs`、`package.json`、
   `package-lock.json`、`AGENTS.md`、`TRANSLATION.md`、`CONTRIBUTING.md`、`agent-docs.config.yml`，
   并把 `.github/workflows/` 下除 `pages.yml` 外的 workflow 删掉，
   同时删掉 `pages.yml` 里的 `Set up Node.js` 与 `Verify advertised and pinned release match` 两步。
5. 后台启动 `hugo server`，确认 http://localhost:1313/ 返回 200 且页面标题是新站点名。
6. 校验：运行 `hugo --gc --minify --printPathWarnings --panicOnWarning`，
   要求以 `Total in ...` 结束且没有 WARN/ERROR；有报错就修到通过，不要用忽略告警的方式绕过。
7. 只在缺少 [站点名称]、[站点域名]、仓库地址这三项信息时才问我，其余按上面的默认做法执行。

建好的站点便于助手读取：每页都有 .md 纯文本输出，站点根有 llms.txt，页面标题右侧的菜单里有「复制 Markdown 文本」与「在 Claude 中打开」。见 Agent 支持。

不从这个仓库起步、要从空目录搭建，见从零建站与其它安装方式。

相关

• 仓库导览 — 每个目录是什么、删的顺序
• 从零建站与其它安装方式 — hugo mod init 起步、submodule 与离线安装
• 本地预览 — hugo server 的常用开关与草稿预览
• 发布上线 — 各家托管的配置与验收清单
• 排错与检查 — 构建、语言、搜索、平台四类常见错误

2.1 - 仓库导览

本页逐项说明 pgsty/oink.pgsty.com 克隆下来的每个文件与目录：哪些必须保留、哪些替换为你自己的信息、哪些是文档站自用可以整棵删除，并给出一个安全的删除顺序。

主题代码不在这个仓库里：它是 go.mod 固定的一个 Hugo Module，存放在 Go 的模块缓存中。这个仓库只有内容、配置与站点自己的少量覆盖。

顶层结构

上面没有列出的还有 .gitignore、.gitattributes、.nvmrc、.npmrc，以及被 .gitignore 排除的生成物：public/（构建产物）、resources/（Hugo 资源缓存）、node_modules/。后一组不进版本库。

仓库里没有 i18n/：界面文字（「上一页」「本页目录」这类）由主题的 32 份语言文件提供。要改其中某一句，在站点根目录建 i18n/zh.yaml，只写需要覆盖的键。

各项的处理方式

删除顺序

顺序是先删外围、再删内容、最后清数据。每删一步构建一次，出问题时能定位到具体步骤。

1. 删脚手架

   这一批与站点渲染无关，删除后不影响任何页面。

   rm -rf tests scripts node_modules
   rm -f package.json package-lock.json playwright.config.mjs .nvmrc .npmrc
   rm -f AGENTS.md TRANSLATION.md CONTRIBUTING.md agent-docs.config.yml Makefile
   rm -f .github/workflows/site-checks.yml .github/workflows/browser-quality.yml

   删除 scripts/ 之后必须改 .github/workflows/pages.yml：把 Set up Node.js 与 Verify advertised and pinned release match 两步删掉，否则部署会在该步骤失败。

2. 删示例内容

   content/docs/ 是 OINK 自己的主题文档，content/blog/ 是它的工程博客，与你的产品无关。

   rm -rf content/docs
   mkdir -p content/docs
   rm -rf content/blog        # 不要博客的话；要的话只留一篇当模板

   同时改 hugo.yml 里每种语言下的 menus.main：那些菜单项指向 /docs/tutorial、/blog/release 这些已不存在的路径。content/_index.md 是首页，保留它，把正文换成你的。

3. 清数据

   data/ 下三组数据分别供首页、Landing 页与发布页使用。首页数据保留后修改，另外两组用不到就删除。

   rm -rf data/landing data/download

   data/home/en.yaml 与 data/home/zh.yaml 决定首页有哪些分区，逐项含义见首页与落地页。删除整个 data/home/ 也能构建，首页退回为普通内容页。

4. 换身份

   最后把 hugo.yml 里的站名、params.productionURL、params.github_repo 与品牌参数换成你的，替换 static/ 下的 logo 与 favicon，删掉 services.googleAnalytics、params.comments 与 params.version* 这些 OINK 专用配置。逐条清单见十分钟上手第 3 步。

主题的位置

主题以 Hugo Module 的形式引用，两处配置指向它：

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: '0.160.1'

require github.com/pgsty/oink v0.6.0

hugo.yml 声明使用哪个主题，go.mod 固定用它的哪一版，go.sum 记录该版本的校验和。三个文件都要提交。主题源码不进你的仓库：Hugo 把它下载到 Go 的模块缓存，hugo mod graph 显示实际解析结果。

升级到最新版：

hugo mod get -u github.com/pgsty/oink

固定到某一个版本：

hugo mod get github.com/pgsty/oink@v0.6.0

两条命令都会改写 go.mod 与 go.sum。生产站点固定到发布标签，不要跟随 main。升级前后检查什么、如何回滚，见版本升级。

站点覆盖

layouts/ 下的文件按 Hugo 的模板查找顺序盖过主题里的同名文件。本站只放了一类：

• layouts/_shortcodes/*.html：站点自己的 shortcode。产品文档需要带业务语义的 shortcode 时也放这里。

标题自链锚点由主题的 _markup/render-heading.html 提供，站点不需要自己建这个钩子。

要改外壳（侧栏、页脚、页尾）时，覆盖最窄的那个 partial，不要整份复制 baseof.html：复制之后每次主题升级都要手工合并。

验证

每删一步运行一次构建，报错能定位到刚删除的内容：

hugo --gc --minify --printPathWarnings --panicOnWarning

删除完成后，这几条应当成立：

• 构建以 Total in … 结束，没有 WARN / ERROR
• 顶栏菜单没有指向已删目录的死链
• 标题右侧仍然有自链锚点（主题自带的标题渲染钩子，站点不需要覆盖）
• git status 里没有 public/、resources/

相关

• 十分钟上手 — 克隆、改配置、部署的完整流程
• 从零建站与其它安装方式 — 从空目录搭建，不做删减
• 组织内容 — content/ 的目录结构怎么变成侧栏
• 配置总览 — hugo.yml 每个键的含义与默认值
• 版本升级 — 升级主题模块与迁移工具

2.2 - 从零建站与其它安装方式

本页从空目录搭建一个最小 OINK 站点：十几行 hugo.yml 加一条 hugo mod get，得到一个可预览的单语站点。代价是首页、示例内容与可参照的组件用法都要自己写。

已有 Hugo 站点时不需要脚手架：装上主题模块，再补三项 goldmark 前置配置（见写 hugo.yml），正文不用重写。已有 Docsy 站点见版本升级。

后半部分是四种安装方式的取舍：Hugo Module、Git submodule、离线归档、固定版本克隆。

从空目录到第一页

1. 建骨架并获取主题

   hugo new site --format yaml my-docs
   cd my-docs
   hugo mod init github.com/example/my-docs
   hugo mod get github.com/pgsty/oink@v0.6.0

   hugo mod init 后面跟的是你自己站点的模块路径，通常就是仓库地址。hugo mod get 会写出 go.mod 与 go.sum，两个都要提交。

   最新版本号在 GitHub Releases；本页出现的 v0.6.0 是本站当前固定的版本。生产站点固定到发布标签，不要跟随 main：@latest 是一次性解析动作，不是版本策略。

2. 写 hugo.yml

   把 hugo new site 生成的 hugo.yaml 改名为 hugo.yml（两个后缀 Hugo 都接受，本文统一用后者），内容替换为下面这份，可直接构建：

   hugo.yml

   title: Product Docs
   baseURL: https://docs.example.com/
   defaultContentLanguage: en
   # enableGitInfo: true        # 页面「最后修改」时间来自 git，先 git init 再打开
   
   languages:
     en:
       label: English
       locale: en-US
       weight: 1
       title: Product Docs
       params:
         description: Everything about running Product in production
       menus:
         main:
           - { name: Docs, pageRef: /docs, weight: 20 }
           - { name: Blog, pageRef: /blog, weight: 50 }
   
   # 三项 Goldmark 前置：OINK 的原生 Markdown 组件全靠它们
   markup:
     goldmark:
       renderer:
         unsafe: true # 允许内容里的行内 HTML
       parser:
         attribute:
           block: true # {.steps} {.cards} {caption=} 这类属性行
         wrapStandAloneImageWithinParagraph: false # 块级图片才能带属性行
     highlight:
       noClasses: false # 代码配色跟随深浅色模式
   
   params:
     offline_search: true
     github_repo: https://github.com/example/product-docs
     copyright:
       authors: '[Example Inc.](https://example.com/)'
       from_year: 2026
     ui:
       dark_mode: true
       sidebar_menu_foldable: true
       section_index: cards
   
   outputs:
     home: [HTML, markdown, LLMS]
     page: [HTML, markdown]
     section: [HTML, RSS, print, markdown]
   
   module:
     imports:
       - path: github.com/pgsty/oink
     hugoVersion:
       extended: true
       min: '0.160.1'

   五段分别管什么：

   段	管什么	少了会怎样
   顶层 + languages	站名、域名、语言与顶栏菜单	baseURL 不对，线上所有绝对链接指错
   markup.goldmark	三项组件前置	属性行变成正文里的一行 {.steps}
   params	搜索、仓库链接、外壳开关	交互功能默认关闭，主题不替站点决定
   outputs	每页的 .md、llms.txt、打印页	页面菜单里没有「复制 Markdown」，也没有打印视图
   module	引用主题、声明 Hugo 下限	构建时找不到主题

   写公式还需要 Goldmark 的 passthrough 扩展，见公式。每个键的完整含义与默认值见配置总览。

3. 写第一页

   content/ 下的每个一级目录是一个分区，目录结构就是侧栏结构。文档分区至少要有一个 _index.md：

   content/docs/_index.md

   ---
   title: Docs
   linkTitle: Docs
   description: Everything about running Product in production.
   weight: 20
   ---
   
   从[安装](/docs/install/)开始。

   content/docs/install.md

   ---
   title: Install
   description: Install Product on a fresh machine.
   weight: 10
   ---
   
   ## Prerequisites {#prerequisites}
   
   > [!IMPORTANT]
   > Product 需要 PostgreSQL 18 或更高版本。
   
   ## Install {#install}
   
   ```bash
   curl -fsSL https://get.example.com | bash
   ```

   标题写显式 {#id}：后续加译文时两种语言的锚点才能对应。页面写法见编写页面。

4. 预览

   hugo server

   打开 http://localhost:1313/，侧栏里有 Docs → Install。修改文件是毫秒级热重载。

其它安装方式

上面用的是 Hugo Module。另外三种方式面向特定约束：网络隔离、平台要求构建输入包含完整主题树、组织内部需要评审主题副本。除 hugo mod vendor 之外，它们都不建立 Go 模块，站点用 theme: oink 而不是 module.imports 引用主题；共同的代价是版本解析与完整性校验由你自己负责。

Hugo Module（推荐）

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/oink@v0.6.0

module:
  imports:
    - path: github.com/pgsty/oink

唯一能让 Hugo 自己解析版本、校验 checksum、并在 go.sum 里留下审计记录的方式。hugo mod graph 看实际解析结果，hugo mod get -u 升级。需要本机有 Go。

Git submodule

在站点仓库里记录准确的主题 commit：

git submodule add https://github.com/pgsty/oink.git themes/oink
git -C themes/oink fetch --tags
git -C themes/oink checkout v0.6.0
git add .gitmodules themes/oink

theme: oink

CI 必须在运行 Hugo 之前初始化 submodule，否则 themes/oink 是空目录：

git submodule update --init --recursive

离线归档

网络隔离环境使用。两条路径，都先在联网机器上准备，再整体搬入。

用 hugo mod vendor：把已解析的主题源码固化进站点目录，之后构建既不联网也不需要 Go。

hugo mod vendor          # 生成 _vendor/，里面是主题的完整源码树
tar czf my-docs.tgz .    # 连 _vendor/ 一起搬进隔离环境

_vendor/ 存在时 Hugo 优先使用它（hugo mod graph 输出 +vendor），hugo.yml 里的 module.imports 保持不变。这一步需要 Go，之后的构建不需要。升级主题要回到联网环境重新执行 hugo mod get 与 hugo mod vendor。

_vendor/ 只收主题挂载出来的目录（assets data i18n layouts static）以及 hugo.yaml 与 theme.toml，不含 LICENSE、NOTICE 与 VENDOR.json。要对外分发这份归档，把这三个文件从主题仓库一并取来。

用 tag 源码归档：不建 Go 模块，直接把某个版本的主题解压到 themes/oink/。

curl -L -o oink.tar.gz \
  https://github.com/pgsty/oink/archive/refs/tags/v0.6.0.tar.gz
mkdir -p themes/oink
tar xzf oink.tar.gz -C themes/oink --strip-components=1

theme: oink

主题仓库的根目录就是模块根目录，解压出来直接是 layouts/、assets/、i18n/、static/ 这一层，不需要再进入下一级。重新分发时必须保留 LICENSE、NOTICE 与 VENDOR.json。最后一个记录了每个第三方运行时的版本、来源、许可证路径与 SHA-256，是离线审计的依据。

跨机器传输时，在联网侧从不可变标签生成归档与校验值：

git clone --branch v0.6.0 --depth 1 \
  https://github.com/pgsty/oink.git oink
git -C oink archive --format=tar.gz --prefix=oink/ \
  --output=../oink-v0.6.0.tar.gz v0.6.0
shasum -a 256 oink-v0.6.0.tar.gz \
  > oink-v0.6.0.tar.gz.sha256

把归档与 .sha256 一起传入隔离环境，先校验再解压：

shasum -a 256 -c oink-v0.6.0.tar.gz.sha256
mkdir -p themes
tar -xzf oink-v0.6.0.tar.gz -C themes

这样得到的归档是自建产物，不是项目发行物。某个标签的发行页面是否附带归档与校验文件按发布而定，使用公开附件时独立验证其校验值。

断网构建之前确认归档内容完整，这十一项都要在：

固定版本克隆

托管平台要求构建输入包含完整主题树时用：

git clone https://github.com/pgsty/oink.git themes/oink
git -C themes/oink checkout v0.6.0

与 submodule 的区别是主题文件直接进入你的仓库历史，没有 .gitmodules 这层间接。记录最终解析出的 commit 与恢复流程。

四种方式对比

用本地主题 checkout 开发

同时修改主题与站点时才需要这一节。把两个仓库克隆为同级目录：

~/pgsty/
├── oink/            # 主题
└── product-docs/    # 你的站点

用环境变量 HUGO_MODULE_REPLACEMENTS 把模块临时替换为本地 checkout，go.mod 不变：

cd ~/pgsty/product-docs
HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> ../oink' hugo server

文档站仓库的 Makefile 就是这几条命令的别名，make dev 与 make check 要求主题 checkout 在同级目录 ../oink：

build:
	hugo --cleanDestinationDir --minify

check:
	HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> $(abspath ../oink)' npm test

dev:
	HUGO_MODULE_REPLACEMENTS='github.com/pgsty/oink -> $(abspath ../oink)' hugo server --renderToMemory

Go workspace（go work init + HUGO_MODULE_WORKSPACE=go.work）是等价的另一种做法。两种做法都只作用于本机：CI 与生产构建用的是 go.mod 里的版本，go.work 不要提交。

验证

hugo mod graph                                       # 主题实际解析到哪一版
hugo --gc --minify --printPathWarnings --panicOnWarning

构建以 Total in … 结束、没有 WARN / ERROR 即通过。再确认：

• /docs/ 打得开，侧栏里有你写的页面
• 顶栏有搜索框，搜得到刚写的标题
• 深浅色切换按钮在，切换后代码块配色跟着变（说明 markup.highlight.noClasses: false 生效）
• git status 里有 go.mod 与 go.sum，没有 public/、resources/

相关

• 十分钟上手 — 另一条路径：克隆文档站再做删减
• 仓库导览 — 文档站的每个目录是什么
• 配置总览 — hugo.yml 每个键的含义与默认值
• 编写页面 — 第一页之后怎么继续写
• 版本升级 — 升级主题模块、从 Docsy 迁移

3 - 创作内容

本栏覆盖 OINK 支持的几种内容类型：文档页、博客文章、书籍、发布下载页、OpenAPI 参考。它们共用同一套 Markdown 与 front matter，各自另有约定。

一页文档的构成

一页文档是一个 Markdown 文件。文件开头两行 --- 之间是 front matter，即页面元数据：标题、侧栏短名、描述、排序。其余部分是正文，内容为普通 Markdown 加 OINK 的原生组件。下面是一个完整页面：

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

## 前提条件 {#prerequisites}

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

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

存为 content/docs/install.zh.md，运行 hugo server 后页面出现在 /zh/docs/install/，侧栏出现「安装」一行。

内容类型与对应页面

3.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 的常用开关

3.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.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 里的站点参数全表

3.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 等键的完整定义
• 组织内容 — 目录与侧栏
• 分类体系 — 标签与分类
• 发布与下载页 — 版本卡片与资产表

3.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：