OINK：文档框架这件事，折腾了六年，终于靠 Codex 毕业了
内容提要
作者历时六年尝试Docsy、Docusaurus等八个文档框架均不满意，遂用AI工具Codex自研Hugo主题OINK。该主题保留Docsy完整功能，采用现代审美，仅依赖Hugo Extended二进制，无需npm和CDN，支持本地全文检索、多语言、离线交付及图表、API文档等工程内容，已应用于Pigsty等站点。
延伸解读
六年试错背后的真实痛点
作者尝试Docsy、Docusaurus等八个框架均不满意，核心矛盾在于功能完备与简洁美观难以兼得。Docsy功能最全但依赖npm、PostCSS等前端工具链，构建复杂且无法直接用Cloudflare Pages自动构建；其他方案或审美不足，或引入Node.js生态负担。这揭示了文档框架选型的长期困境：需求会随项目生长，而维护成本往往被低估。
消费端只依赖Hugo的工程意义
OINK将站点构建边界收缩到Hugo Extended，生产构建只需hugo命令，无需npm install或CDN拉取运行时。所有资源本地交付，带来构建可复现、供应链可审计、内网离线可用等好处。对需要离线文档分发的团队而言，这不仅是便利，更是必备能力。托管层无需感知OINK，静态产物可部署到任意环境。
按需加载与检索索引优化
OINK通过短代码标记和资源组装阶段检查，实现按需加载：只有用到ECharts的页面才加载ECharts，纯文字文章不背负额外运行时。全文检索索引不再随首页下载，仅当用户按下搜索框时才首次加载。作者提到某站点每月八百多GB流量中大半被索引消耗，这一优化同时改善了流量成本和用户体验。
多语言与SEO的细节处理
OINK的语言模型基于Hugo多语言页面对象，不从域名或硬编码URL猜测语言。缺少译文时链接回退到目标语言首页，避免404；每种语言有独立检索索引，防止搜索结果混杂。HTML lang、canonical、hreflang和Open Graph locale均来自同一翻译对象，避免界面语言与SEO元数据不一致的漂移问题。
Q&A
OINK 是什么？为什么作者要开发它？
OINK 是一个基于 Hugo 的文档主题框架，由作者冯若航开发。作者在六年里尝试了 Docsy、Docusaurus 等八个文档框架，但都不满意：功能全的 Docsy 太丑且依赖繁多，好看的方案又缺功能或依赖 Node.js。于是作者用 AI 工具 Codex 自研了 OINK，目标是保留 Docsy 的完整功能，采用现代审美，同时只依赖 Hugo Extended 二进制，无需 npm 和 CDN。
OINK 在构建和依赖方面有什么特点？
OINK 将消费端站点的构建边界收缩到 Hugo Extended，生产构建只需运行 hugo 命令。没有 npm install、PostCSS、node_modules，构建时也不从公共 CDN 拉取运行时。Bootstrap、Font Awesome、字体、Lunr 搜索、Mermaid、KaTeX、Swagger UI 等资源全部跟随主题源码本地交付，因此构建可复现、供应链可审计，也适合内网和离线环境。
OINK 支持哪些工程文档内容？
OINK 支持 Asciinema 终端录像、Apache ECharts 数据图表、AntV Infographic 信息图、Mermaid、KaTeX、Markmap、PlantUML、Diagrams.net、Swagger UI 与 Redoc API 文档，以及步骤、标签页、折叠块、卡片、卡片组和文档轮播等组件。评论系统还支持读者使用 GitHub 账号登录。
OINK 的多语言功能是怎么实现的？
OINK 的语言模型直接建立在 Hugo 的多语言页面对象上，不从域名或硬编码 URL 猜测语言。只有一种语言时语言选择器自动隐藏；配置两种或更多语言时，按钮按权重切换，完整菜单列出所有语言。当前页面缺少目标译文时，链接会回退到目标语言首页，而不是生成 404 地址。每种语言拥有独立的本地检索索引，HTML lang、书写方向、canonical、hreflang 和 Open Graph locale 都来自同一组翻译对象。
OINK 适合哪些场景，不适合哪些场景？
OINK 适合维护开源项目、数据库、基础设施、内部平台等需要长期演进的工程产品，尤其需要多语言、离线交付、可审计依赖和稳定静态部署的场景。不适合需要多人在线协作 CMS、用户登录后的动态内容、实时数据后台或完整前端应用框架的场景。OINK 是一款 Hugo 主题，不是 SaaS，也不是应用服务器。
如何开始使用 OINK？
OINK 0.2.0 要求 Git、Go 和 Hugo Extended 0.160.1 或更高版本。在 Hugo 站点根目录初始化模块并固定版本：hugo mod init github.com/example/product-docs 和 hugo mod get github.com/pgsty/[email protected]。然后在 hugo.yaml 中导入主题：module: imports: - path: github.com/pgsty/oink。最后运行 hugo server 启动预览。已有 Docsy 站点理论上可以直接迁移。
