01 / 工程文档
为工程师与文档站设计
◇ 从可运行的模板开始，逐步完善自己的站点
- Starter 与部署指南帮助你完成第一个站点
- 自带全文检索、i18n 与多版本支持
- 自带 RSS、SEO 与 Google Analytics 集成
内容团队可以把时间用在文档上，而不是重复搭建站点基础设施。
OINK 1.2 · 本地优先 · Hugo 构建
PGSTY OINK
用 Markdown 创作技术内容。
用四套风格呈现文档、博客、书籍与 API 参考。
价值主张
工程文档所需的能力，开箱即用
让技术内容共用导航、搜索与发布工具。
02 / 四套风格
四套风格，同一个站点
◇ Paper · Slate · Ink · Terminal
- Paper 使用暖色纸面与克制排版； Slate 保留原有技术风格
- Ink 用黑白与红色建立对比；Terminal 将等宽标题与易读的无衬线正文搭配
- 在外观菜单中独立选择风格与明暗，翻页后仍保留你的偏好
内容不变，风格自选。字体与核心脚本均由本地提供。
03 / 本地优先
使用 Hugo 构建
◇ 资源随主题内置，无需 npm 构建流程
- 一条 hugo 命令完成全部构建
- 无需 npm install 或 PostCSS 构建
- 内置资源本地提供；备齐依赖后可离线构建
Hugo Modules 需要 Go 解析模块，外部服务由站点按需接入。
build.sh
# 一条命令，一份确定性输出
$ hugo --gc --minify
✓ 本地资源已打包
✓ 多语言路由已生成
✓ public/ 可以部署
04 / 功能扩展
功能扩展
◇ 把工程内容需要的表达能力直接带进主题
- Code Group、FileTree 与 Fields 覆盖日常技术写作
- Gallery、Image Zoom 与图表组件用于视觉化说明
- 组件明确说明 Markdown 与打印输出； 交互内容按需保留源码或静态说明
组件脚本只在使用该组件的页面加载。
不止文档
六种内容形态，同一套外壳
文档站很少只有文档。那些通常需要第二个工具的内容形态，在这里共用同一套外壳、检索与输出。
文档
侧栏树、页内目录、面包屑、翻页、编辑与历史链接——其它内容类型复用的就是这套外壳。
博客与 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 是 Pigsty 背后的公司。这个小型双语公司站主要将 OINK 用作数据驱动的落地页系统。.
pigsty.cc开源 PostgreSQL 发行版 Pigsty 的中文主站。独立部署的单语站让大规模中文语料按自己的节奏持续演进。.
pigsty.io开源 PostgreSQL 发行版 Pigsty 的英文主站，将大型发行版手册、博客、扩展目录与价格落地页集中在一起。.
silo.pgsty.comSILO 是社区维护的 MinIO 分支，提供兼容 S3 的对象存储。这个大型双语迁移案例从经过检查的清单生成文档导航。.
oink.pgsty.comOINK 是本案例库各站点采用的 Hugo 主题。本站将公开手册、设计参考、组件示例与回归测试集中在同一仓库。.
caps.vonng.comCapslock 把 Caps Lock 变成第五个修饰键。这个每种语言仅两页的小站，将项目介绍与数据驱动的交互配置器放在一起。.
pig.pgsty.comPIG 是 PostgreSQL 扩展包管理器。这个案例将精简的双语产品手册与数据驱动首页、持续更新的博客配合使用。.
sow.pgsty.comSOW 用于构建与镜像 APT、YUM 软件仓库。双语运维手册与下载页共享结构化发布元数据。.
exp.pgsty.comPG Exporter 是面向 PostgreSQL 与 PgBouncer 的 Prometheus 指标采集器。这个双语手册结合了生成导航、结构化指标目录与系统字体。.
ddia.vonng.com《设计数据密集型应用》的多语言书籍站，也是 OINK 图表编号、交叉引用与索引的重要应用案例。.
tpme.vonng.com《The Product-Minded Engineer》的双语书籍站，以精简的 OINK Book 外壳组织长篇阅读。.
pgint.vonng.com《PG 技术内幕》的中文译本站。它只使用 Book 阅读外壳，没有另建文档树。.
PostgreSQL 组件文库PostgreSQL 组件运维文库：让多个上游手册与完成度不一的翻译树共享搜索和视觉体系。.
pgsty.proPIGSTY PRO 是 Pigsty 的企业版。双语文档与版本档案围绕可复用的结构化发布记录组织。.
ext.pgsty.comPostgreSQL 扩展目录。案例快照收录 2,241 个扩展，其中 576 个已打包，可按 16 个 Linux 平台与 5 个 PostgreSQL 大版本查询。.
选型之前
值得先问的几个问题
哪里需要 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、对中日韩文本用子串回退，无需托管服务也能搜索。OINK 1.2 提供 32 份原生界面语言包、符合当地语言规则的复数形式与已翻译的外观控件，包括英语、 简体中文（zh-cn、zh）和繁体中文（zh-tw）。支持 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 构建发布。