OINK 实施日记：从复制外壳到统一主题

Sat, 08 Aug 2026 00:00:00 +0000

OINK 始于一个令人不安的事实：多个生产文档站之所以看起来相互关联，是因为它们确实源于同一套实现；但公共实现却以复制文件的形式散落在各处。呈现效果足够一致，维护模型却并非如此。

这篇日记记录项目如何从重复站点覆盖项走向一款直接演化的统一主题。它关注决策与证据，而不是逐条复述提交历史。

锁定产品契约

第一项真正有价值的工作是做减法。选择实现方式之前，我们先写清产品必须是什么：

这排除了一个看似诱人、实际代价高昂的捷径：增加 params.oink.enabled 并保留旧外壳。模式开关会让每次布局调整、无障碍修复与测试都支持两套产品。直接演化则让目标设计成为唯一设计。

文档、博客与 API 参考布局围绕一组小型共享 partial 重新构建。新的外壳包括：

真正困难的不是画出导航栏，而是在删除复制的 baseof.html 时保留 Docsy 既有扩展点。范围明确的 hook 仍然存在；复制整个站点外壳不再是正常的定制路径。

原有依赖链假设 Bootstrap 与 Font Awesome 来自 npm，部分路径还会调用 PostCSS。OINK 把必需源码与编译产物移入主题，并让 SCSS 留在 Hugo 自身的 Asset Pipeline 中。

测试不只检查 hugo 是否成功。fixture 中的陷阱会在消费端构建尝试运行 Node.js、npm、PostCSS 或 Autoprefixer，或模板调用 resources.GetRemote 时立即失败。LTR 与 RTL 页面遵守同一约束。

Sat, 08 Aug 2026 00:00:00 +0000

今天，我们发布 OINK 实现预览：它从 Docsy 直接演化而来，提供唯一标准产品外壳、仅依赖 Hugo 的消费端构建、本地优先浏览器依赖、通用多语言框架，以及一组从 PGSTY 文档站提炼出的可复用内容组件。

这是实现与文档里程碑，不是已经公开的版本化发行。最终公开品牌、模块与软件包身份、首个版本，以及生产 Cloudflare Pages 部署，仍是必须显式关闭的发布关卡。

多个成熟文档站分别复制了相同的 Docsy 布局、导航、搜索代码、SCSS、JavaScript 与短代码。一个公共修复必须在多个仓库重复实施；与此同时，每个站点都携带前端工具链与隐含网络依赖，让网络隔离构建变得异常复杂。

OINK 将真正可复用的部分合并到主题中。产品矩阵、门户、价格页和其他业务专用行为仍留在各自站点；共享主题负责文档外壳、浏览器运行时、多语言路由、无障碍行为与内容组件契约。

OINK 不是可选皮肤。项目没有 oink.enabled 开关、params.oink.* 命名空间，也没有“上游版与品牌版”并行的模板树。theme/ 中的实现就是产品。

这项决策避免维护两套视觉系统与两套测试矩阵。Hugo 原生设置与兼容的 Docsy 参数继续保持原有含义。

完整消费站点只需运行：

hugo --gc --minify

Bootstrap、Font Awesome、字体、搜索、图表、API 文档运行时与 OINK 组件都已随主题提交。Node.js、npm、PostCSS、Autoprefixer 与 CDN 下载不属于消费端要求。

仓库维护者仍会使用 Node 工具运行测试和更新 vendor 资源；这套维护工具链有意置于公开站点构建契约之外。

默认 starter 会从生成后的站点提供页面外壳、字体、图标、搜索、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts 与 Infographic 依赖。可选运行时按页面选取，并且每页最多加载一次。