价值主张
工程文档所需的能力，开箱即用
工程文档所需的一切——内置、本地、按需加载。
03 / 本地优先
本地优先，无外部依赖
◇ CSS、JavaScript、字体与运行时全部本地化
- 一条 hugo 命令完成全部构建
- 无需 npm install 或 PostCSS 构建
- 所有资源本地提供，断网也能服务
开发、CI 与生产环境使用同一条可确定的构建路径。
# 一条命令，一份确定性输出
$ hugo --gc --minify
✓ 本地资源已打包
✓ 多语言路由已生成
✓ public/ 可以部署
04 / 功能扩展
功能扩展
◇ 把工程内容需要的表达能力直接带进主题
- Code Group、FileTree 与 Fields 覆盖日常技术写作
- Gallery、Image Zoom 与图表组件用于视觉化说明
- 每个组件都有语义化 Markdown 与打印输出，只在交互确实需要时加载 JavaScript
富内容能力属于主题，普通页面不会因此背上额外负担。
不止文档
六种内容形态，同一套外壳
文档站很少只有文档。那些通常需要第二个工具的内容形态，在这里共用同一套外壳、检索与输出。
文档
侧栏树、页内目录、面包屑、翻页、编辑与历史链接——其它内容类型复用的就是这套外壳。
博客与 RSS
按时间排列的文章、按数量排序的标签面板，以及按语言分别生成的订阅源。
书籍
章节编号，图表公式用 {#id num=} 编号、xref 交叉引用，整本可打印。
发布与下载
一份 data/download/*.yaml 生成发布卡片、资产表与校验和，发布状态是数据。
Landing 页
用二十二种服务端渲染分区拼装页面，你正在读的这一页就是其中之一。
API 参考
Swagger UI 与 Redoc 都是本地运行时，规范文件放在仓库里，离线可用。
组件参考
二十一个组件，按需加载
每个组件都有独立的一页，并在 HTML、打印、Markdown 与 RSS 下有确定形态；交互运行时只随用到它的页面下发。
ECharts
echarts 数据围栏
信息图
声明式数据围栏
思维导图
大纲变成导图
Asciinema
终端录像，本地播放
PlantUML
UML，需自建渲染服务
Draw.io
可回编辑的图
Mermaid
本地图示运行时
数学公式
KaTeX 构建期渲染
文件树
filetree 数据围栏
画廊
gallery 数据围栏
代码块
Chroma · 行号 · 复制 · 折叠
图片
图注 · 尺寸 · 缩放
表格
标题 · 编号 · 矩阵
参数表
表格加 {.fields}
提示块
> [!NOTE] · 十种类型
标签页
围栏加 {tab=}
步骤
列表加 {.steps}
卡片
列表加 {.cards}
徽章
行内状态，五种 tone
按键
键位与组合键
引用
引入文件、参数与构建注释
案例
十五个站点，同一个家族
中文、英文与双语；发行版手册、产品文档、三本书、公司主页、扩展目录，以及一个两页的小工具。每张卡片都会打开线上站点，案例库 说明每个站点背后的内容模型。
pgsty.comPGSTY: the company behind Pigsty.
pigsty.ccPIGSTY: the Chinese home of the open-source PostgreSQL distribution.
pigsty.ioPIGSTY: the English home of the open-source PostgreSQL distribution.
silo.pgsty.comSILO: the community-maintained MinIO fork for S3-compatible object storage.
oink.pgsty.comOINK: the Hugo theme every site in this library is built with.
caps.vonng.comCapsLock: turn the most useless key on the keyboard into a fifth modifier.
pig.pgsty.comPIG: the package manager that installs any PostgreSQL extension.
sow.pgsty.comSOW: the repository manager that builds and mirrors APT and YUM software repositories.
exp.pgsty.comPG Exporter: the Prometheus metrics exporter for PostgreSQL and Pgbouncer.
ddia.vonng.comDDIA: the Chinese edition of Designing Data-Intensive Applications.
tpme.vonng.comTPME: the Chinese edition of The Product-Minded Engineer.
pgint.vonng.comPG Internals: the Chinese edition of PostgreSQL Internals.
pgsql.ccPGSQL.CC: an operations library for PostgreSQL and the components around it.
pgsty.proPIGSTY PRO: the enterprise edition of Pigsty.
ext.pgsty.comPGEXT: the PostgreSQL extension catalog.
选型之前
值得先问的几个问题
哪里需要 Node.js、npm 或打包器吗？
不需要。构建依赖只有 Hugo Extended（0.160.1 或更新）。Go 只用一次，用来把主题解析为 Hugo Module；离线归档或 Git submodule 方式连 Go 也不需要。界面交互仍在浏览器里执行 JavaScript，但这些脚本随主题分发，只挂在用到它们的页面上。
我有一个 Docsy 站，迁移有多难？
内容与 front matter 大多可以直接沿用，替换的是外壳、导航、检索与组件。改名的配置键会让 构建失败并给出新名字，bin/migrations/oink06.py 在改写之前先报告它会改什么。 见升级与迁移。
OINK 只适合大型文档树吗？
不是。样例站点里既有两页的项目站，也有一千五百个文件的发行版手册， 还有一个只用 OINK 做落地页的公司站。外壳向下缩放和向上扩展一样自然。
中文与其它非拉丁文字的内容怎么处理？
本地检索对拉丁文字用 Lunr、对中日韩文本用子串回退，无需托管服务也能搜索。英语、简体中文 （zh-cn、zh）与繁体中文（zh-tw）的界面文案经过人工审校，另外 28 种语言共用同一套 key。支持 RTL 布局。
AI 助手与爬虫拿到的是什么？
outputs 里加上 markdown，每个页面就有一份 index.md，由 rel="alternate" 指过去； LLMS 输出格式在站点根目录写出 llms.txt。「在 ChatGPT / Claude 中打开」这类页面动作 存在，但默认关闭，因为它会把读者的 URL 交给第三方。
许可证是什么？和 Docsy 是什么关系？
Apache License 2.0。OINK 是 Docsy 的分叉并独立演化；Docsy 的源码历史、署名与 Apache-2.0 义务完整保留，每个随主题分发的运行时都在 VENDOR.json 里连同许可证列出。 见开源许可与致谢。
从一个已经能运行的仓库开始。使用 OINK Starter，替换身份与内容，再通过 warning 即失败的 Hugo 构建发布。