OINK 是什么

• 1: 亮点特性
• 2: Case 导览
• 3: 开源许可与致谢

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 生成的静态文件可用任何托管平台发布。站点自己的内容、品牌与业务组件仍归站点管理，主题只提供通用外壳与可复用组件。

适用范围

这些情况适合	这些情况不适合
页面多、内容类型杂：文档、博客、书、发布页与 API 参考共处一个站点	只有一两页内容、不需要结构化导航；README 或更轻的 Hugo 主题更简单
需要完整的多语言，而不是给英文站挂一个翻译入口	站点主体是应用界面而不是文档：可以用 OINK 承载文档部分，业务组件留在站点层
对可复现构建与网络隔离有要求，构建机不能出网	需要在正文里写交互组件（React / MDX）
多个站点共享同一套外壳，不必复制布局与 shortcode	想用一个开关换成另一套视觉：主题没有品牌开关，改外观要走 CSS token 与 partial 覆盖
团队没有前端，也不维护 Node 工具链	需要主题内置内容管理后台或所见即所得编辑器

与其它文档方案的差别

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

维度	OINK	Docsy	Hextra	Docusaurus
构建工具	Hugo Extended，单个二进制	Hugo Extended + Node/npm	Hugo	Node.js 工具链
消费站点要不要 npm	不要	要：Bootstrap 与 Font Awesome 从 node_modules/ 挂载	不要	要
前端资源从哪来	全部提交在主题仓库，VENDOR.json 记录版本、来源、许可与校验值	每页无条件加载 CDN 上的 jQuery；Mermaid、KaTeX 等还会在构建期请求 CDN	预编译产物提交在仓库	npm 依赖
组件写法	Markdown 原生属性与围栏为主，29 个 shortcode 兜底	shortcode（19 个）	shortcode（29 个）为主，提示块有 > [!NOTE] 原生形态	MDX（React 组件）
多语言	Hugo 多语言 + 32 个界面语言包	Hugo 多语言（OINK 的语言包由此继承）	Hugo 多语言 + 21 个界面语言包	内置 i18n 框架
书籍编号与交叉引用 / 发布下载页 / 数据驱动落地页	主题内置	无	无	需自建或找插件

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

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

入口

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

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

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

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 夹具，而不是起步模板；其中页面的职责是 触发渲染行为。上面的生产案例更适合作为架构与设计参考。

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

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