OINK:文档框架这件事,折腾了六年,终于靠 Codex 毕业了

做一个文档网站并不难，难的是让它五年之后依然好用。

最初你只想把几份 Markdown 放到网上。

后来需求就开始自己长了：全文检索、深色模式、多语言、多版本、API 文档、流程图、终端录像、移动端适配、SEO、RSS、评论、访问统计、打印导出……

再往后你抬头一看，自己已经在维护一套前端工程了：Node.js、npm、PostCSS、几十个依赖包，还有一堆不知道哪天会失效的 CDN 链接。

文档本来是用来降低项目维护成本的，最后自己变成了一个需要维护的项目。

这就是我做 OINK 的原因。

https://oink.pgsty.com

一、六年，八个方案，没一个满意的

这几年我在文档框架上花的时间，一点都不比别人少。因为文档是一个开源项目的门面——用户在下载你的软件之前，先看到的是你的文档站。门面这个东西，你可以说它不重要，但你不能让它难看。

我试过的方案，大概能列一个考古清单：

•Docsify：纯 JS 加 Markdown，轻量到几乎没有构建步骤，代价是 SEO 和首屏；•Docusaurus：React 生态标配，功能齐全，但你从此接手了一整个 Node 项目；•Hugo + Hextra：够快够简单，但功能面不够工程文档用；•Next.js + Fumadocs：前端审美一流，问题是全文检索慢、内容是 MDX 不是纯 Markdown，想弄成纯静态站还挺费劲；数据库老司机勇闯现代前端大观园

•Mintlify 这类文档 SaaS：确实省事，但你的文档从此托在别人手里；•Docsy：功能最全面的那一个。Google 出品，Kubernetes、etcd 一大堆耳熟能详的项目都在用，可以说是 CNCF 项目的标配。五六年前我第一次给 Pigsty 搭文档站，用的就是它。

Pigsty官方网站上线啦！

Docsy 的问题只有一个，但很致命：太丑了。

而且 Docsy 为了在 Hugo 上支持那么多功能，硬生生塞进了一整套前端工具链——NPM、node_modules 全家桶、PostCSS 预处理 SCSS、Autoprefixer。Hugo 本来是个「下载一个二进制就能跑」的东西，被这么一套下来，构建、预览、维护全都变复杂了。

最直观的后果：用 Cloudflare Pages 都没法直接构建。你得先在 GitHub Actions 里跑一遍 CI、npm install、生成成品，再回到 Cloudflare 那边配置发布。就为了一个静态文档站。所以我的处境很尴尬：功能最全的那个太丑，最好看的那个不够工程化，最省事的那个不在我手里。

那为什么不自己写一个？

因为我真的没空 —— 前端这些东西非常费精力，折腾起来很费劲，而且跟我的主业一点关系都没有。我是个数据库老司机，不是前端工程师。为了一个文档主题去啃几个月的 SCSS 和 JS，这笔账我算了六年，每次都算不过来。

二、直到前端交付变成了可以按需购买的商品

从上个月开始，这笔账突然算得过来了。

顶级的前端设计与实现能力，变成了一种按 Token 计费的通用商品。我不需要成为前端工程师，我只需要清楚地知道自己想要什么——而这件事我想了六年，早就想得非常清楚了。

于是我第一次可以用「许愿」的方式把它做出来：

我要 Docsy 的完整功能集，缝上 Fumadocs / Nextra 的前端审美，加上工程文档真正需要的那些能力，然后把乱七八糟的依赖统统扔掉——一个干净的 hugo 二进制就能构建、就能跑起来。

诚实地说，这是我在 AI 帮助下完成的。但它和那些玩票性质的 vibe coding 不一样：AI 没有替我制造这个需求，需求已经在那儿摆了六年了。AI 做的事情是把「值得动手」的门槛往下拉了一大截。

前几天有人问我，你那七个 AI 订阅每天烧那么多 token，到底烧出什么来了？

这就是其中一个。整套框架加上六七个文档站，前后大概只花了两三天——甚至因为真正的大活儿太多，我一直没抽出时间写这篇文章。

三、为什么叫 OINK

OINK 在英语里是猪叫声。

我的主力开源项目叫 Pigsty，猪圈。这两年围绕它长出来的一系列组件，也都跟猪脱不了关系：

•Pig —— 包管理器，小猪；•Sow —— 仓库管理器，母猪，同时也有「播种」的意思；•Boar —— 图形管控平台，野猪;•Silo —— 对象存储，农场里的谷仓。

猪圈里已经有三头猪了。文档项目总不能再抓一头猪进来，那就让这几头猪叫出来——它们的内容，最后都是通过 OINK 表达出去的。

另一层双关是，OINK 里面藏着 ink，墨水。这跟文档的关系就很紧密了。

再正经一点，这四个字母还真能凑一个说得过去的缩写：

Open · Indexed · Navigable · Knowledge 开放、可索引、可导航的知识。

四、砍掉的部分：只依赖一个 Hugo

OINK 最重要的一个设计决定，是把消费端站点的构建边界收缩到 Hugo Extended。

一个站点的生产构建命令，只有这一条命令：hugo 。没有 npm install，没有 PostCSS，没有 node_modules，构建时也不去公共 CDN 拉运行时。

Bootstrap、Font Awesome、字体、Lunr 搜索、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic——这些全部跟随主题源码本地交付。

好处很朴素：构建可复现，供应链可审计，内网和网络隔离环境也好交付。我自己做离线文档分发时，文档需要在断网环境里能翻能查——对我来说这是个必备能力，不是加分项。

拿到完整主题之后，Hugo 会把内容、配置、布局和资源一次性编译成 public/ 目录。之后你扔到对象存储、GitHub Pages、Cloudflare Pages、Nginx 还是内网文件服务器上，托管层完全不需要知道 OINK 是什么东西。

五、加上的部分：一套现代文档外壳

传统 Hugo 主题常给人一种「能用，但像十年前」的感觉。OINK 想在保留 Hugo 简单交付的同时，把现代文档产品该有的东西补齐：

•全局导航、面包屑、可折叠并且可调宽度的侧栏；•页面目录、阅读元数据、上下页导航、编辑与反馈入口；•深浅色模式、版本选择器、打印视图、移动端操作面板；•RSS、SEO、canonical、hreflang 与 Open Graph 元数据；•本地全文检索（⌘K），以及可选的 Algolia 和 Google 托管搜索；•博客、分类、标签、评论、特色图片与多语言信息架构。

首页也不再是一份「必须复制出来才能改」的 HTML 模板。0.2.0 提供了 12 种可组合分区：Hero、指标、能力叙事、原则、卡片、Logo 墙、画廊、用户评价、贡献者、FAQ、自由 Markdown 与 CTA。站点只要在 data/home/<language>.yaml 里声明顺序和内容，就能重排、复用甚至删掉首页模块。

这条边界我认为很重要：配置应该表达站点想要什么，而不是暴露主题内部是怎么拼装的。

顺手说一个我特别在意的优化。站点大了之后，全文检索索引可能有十几兆——我之前那个网站一个月八百多 G 流量，其中一大半是被这个索引吃掉的。现在首页加载时不再拉索引，等用户真的按下搜索框才首次加载。流量账单和用户体验，居然是同一个方向的优化。

六、工程内容，不该退化成截图

工程文档不只有文字和代码块。

一个数据库或基础设施项目，经常需要终端演示、架构图、时序图、性能图表、数学公式、API 参考、信息图，还有可交互的参数说明。过去这些能力散落在各个站点自己的短代码里，复制到下一个项目再改一遍。

OINK 把已经证明通用的那些整理成了稳定的创作接口：

•Asciinema 终端录像；

•Apache ECharts 数据图表 / AntV Infographic 信息图；•Mermaid、KaTeX、Markmap、PlantUML、Diagrams.net；•Swagger UI 与 Redoc API 文档；•步骤、标签页、折叠块、卡片、卡片组与文档轮播；•Docsy 原有的 alert、include、readfile、image、blocks 等能力全部保留。

还支持使用 Github 账号登录评论

关键在于：这不是把一整套前端运行时塞进每个页面。 短代码渲染时会在 Hugo 的页面状态里标记自己，资源组装阶段再检查标记——只有用到 ECharts 的页面才加载 ECharts，同一页出现十张图也只加载一次。一篇纯文字的文章，不会因为主题「支持很多功能」就背上所有运行时。

这也是我对「功能丰富」的理解：不是让每个页面都携带全部能力，而是让作者随时可用，让读者只为当前页面真正需要的能力付出下载成本。

七、多语言不是复制一个 `/zh` 目录

OINK 的语言模型直接建立在 Hugo 的多语言页面对象上，不从域名或硬编码 URL 去猜语言。

只有一种语言时，语言选择器自动隐藏；配置两种以上时，按钮按权重切换，完整菜单列出所有语言。当前页面缺少目标译文时，链接会回退到目标语言首页——而不是给你造一个看起来很合理、点进去 404 的地址。

每种语言拥有独立的本地检索索引，英文结果不会混进中文搜索。HTML lang、书写方向、canonical、hreflang 和 Open Graph locale 都来自同一组翻译对象，避免那种「界面切成中文了，SEO 还说自己是英文」的漂移。

自产自用

做文档框架有个大忌：光顾着搭架子，结果没内容往里放。能用上才是本事。

所以我很快把自己这一摊子网站全都统一到了 OINK 上：

•pigsty.io^[4] / pigsty.cc^[5] —— Pigsty 这个 PostgreSQL 发行版的英文站与中文站，最大的一个用例；

•silo.pgsty.com^[6] —— 刚发布的 Silo，MinIO 的社区 fork；

•pig.pgsty.com^[7] —— PostgreSQL 包管理器，装扩展用的；

•sow.pgsty.com^[8] —— APT / DNF 仓库管理器，和 Pig 正好凑成一对；

•exp.pgsty.com^[9] —— 老早做的 PG Exporter，现在终于有自己的网站了；

•pgsty.com^[10] —— GitHub 组织与公司官网主页；

•oink.pgsty.com^[11] —— OINK 自己的文档站，当然也用自己的主题。

虽然它是为开源项目和工程文档设计的，但拿来做别的也没问题。我翻译的那几本书，现在也在陆续改用这个框架，大概有六七本。

三分钟开始用

OINK 0.2.0 要求 Git、Go 和 Hugo Extended 0.160.1 以上（当前项目站用 0.164.0 验证）。在 Hugo 站点根目录初始化模块并固定版本：

hugo mod init github.com/example/product-docshugo mod get github.com/pgsty/oink@v0.2.0

在 hugo.yaml 里导入主题：

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

然后启动预览：

hugo server

完整的双语站点结构、配置与部署方式，可以直接看 OINK 开始使用指南^[12]。手上已经有 Docsy 站点的，走从 Docsy 迁移^[13]这条路——理论上任何 Docsy 站点都可以直接换过来。反正上面那么多样例站点，随便弄一个下来改一改就可以用了。

十二、OINK 适合谁，不适合谁

适合：你维护的是开源项目、数据库、基础设施、内部平台，或者其他需要长期演进的工程产品；你需要多语言、离线交付、可审计依赖、富技术内容和稳定的静态部署。

不适合：你要的是多人在线协作 CMS、用户登录后的动态内容、实时数据后台，或者一整套前端应用框架。OINK 是一款 Hugo 主题，不是 SaaS，不是应用服务器，也不打算把一个静态文档站伪装成万能平台。

我喜欢 Hugo，恰恰是因为它足够无聊：一个二进制、一棵内容树、一条构建命令，和一份可以扔到任何地方的静态产物。OINK 想做的，不是用一个复杂框架重新包装这份简单，而是把现代工程文档真正需要的能力，压回这条简单的路径里。

一套好的文档框架，不应该让作者意识到它每天都在工作。

它只应该让内容更容易写，让答案更容易被找到，让知识在几年之后仍然能构建、能阅读、能迁移。

这就是 OINK：oink.pgsty.com^[14]

参考阅读

•《老冯上新：博客文档书籍翻新大作战》•《数据库老司机勇闯现代前端大观园》•《Pigsty 官方网站上线啦！》

References

[1] OINK: https://oink.pgsty.com/zh/[2]pgsty/oink: https://github.com/pgsty/oink[3]pgsty/oink.pgsty.com: https://github.com/pgsty/oink.pgsty.com[4] pigsty.io: https://pigsty.io/[5] pigsty.cc: https://pigsty.cc/[6] silo.pgsty.com: https://silo.pgsty.com/[7] pig.pgsty.com: https://pig.pgsty.com/[8] sow.pgsty.com: https://sow.pgsty.com/[9] exp.pgsty.com: https://exp.pgsty.com/[10] pgsty.com: https://pgsty.com/[11] oink.pgsty.com: https://oink.pgsty.com/zh/[12] OINK 开始使用指南: https://oink.pgsty.com/zh/docs/tutorial/[13] 从 Docsy 迁移: https://oink.pgsty.com/zh/docs/upgrade/migrate-from-docsy/[14] oink.pgsty.com: https://oink.pgsty.com/zh/