关于 on OINK

示例站点

Mon, 01 Jan 0001 00:00:00 +0000

OINK 提供三种不同规模的示例。请选用足以回答当前问题的最小示例：完整项目站适合回归验证，但它有意包含比普通消费站点更多的内容。

选择合适的示例

示例	最适合验证的内容	仓库或指南
双语项目站	生产规模的配置与质量检查	`pgsty/oink.pgsty.com`
主题 `exampleSite/`	落地页组合与主题 checkout	`pgsty/oink/exampleSite`
最小双语消费站点	从零新建文档站	从零新建站点

双语项目站

pgsty/oink.pgsty.com 是你正在阅读的完整文档与回归站。它把英文和简体中文内容并列保存，在 go.mod 中固定已发布的 Oink 模块，并覆盖文档、博客、搜索、打印、富内容、元数据与响应式导航。

使用 Hugo 克隆并预览公开模块路径：

BASH

git clone https://github.com/pgsty/oink.pgsty.com.git
cd oink.pgsty.com
hugo server --disableFastRender

创建生产构建产物：

BASH

hugo --gc --minify

Node.js 与 npm 只是本仓库执行格式、翻译、链接、浏览器和回归检查时的维护依赖，并不是 Oink 消费端的构建要求。

主题示例站

主题仓库包含一个刻意保持精简的 exampleSite/。它直接使用当前 checkout 中的主题，演示可组合落地页，不会引入项目站的文档内容或 npm workspace。

本地优先运行

Mon, 01 Jan 0001 00:00:00 +0000

OINK 的本地优先原则很简单：由主题提供的功能，不得暗中依赖公共 CDN、构建期下载或未经配置的公共服务。完整发行包能够在网络隔离环境中构建，其核心页面也能在该环境中浏览。

本地优先覆盖的范围

主题会从生成后的站点提供以下依赖：

能力	本地交付方式
页面外壳与响应式界面	Bootstrap 与 OINK CSS/JavaScript
图标与字体	Font Awesome、Open Sans、Chakra Petch、IBM Plex Mono
搜索	Lunr、CJK 子串回退与按语言生成的索引
图表与公式	Mermaid、KaTeX 与 Markmap
API 文档	Swagger UI 与 Redoc
富内容	Asciinema、ECharts、Infographic 与轮播运行时

这些资源提交在 assets/ 或 static/ 中。Hugo 会按照站点 baseURL 发布它们，部署在子路径时也不例外。

本地优先不覆盖的范围

OINK 无法让作者任意添加的内容自动离线。以下项目仍然是显式网络选择：

外部链接、远程图片、视频、iframe 与 API 规范；
Algolia、Google CSE 等托管搜索；
分析、评论、身份提供商与其他 SaaS 集成；
作者主动选择远程渲染器时的 PlantUML 或 Diagrams.net。

使用这些功能的页面仍然可以是有效页面，但站点不应再宣称该页面能够完全离线使用。

依赖服务的图表

PlantUML 与 Diagrams.net 不同于纯浏览器库：其常规工作流依赖渲染或编辑服务。因此 OINK 不提供隐含的公共端点。

架构

Mon, 01 Jan 0001 00:00:00 +0000

Oink 是一款直接运行于 Hugo 的主题，而不是应用服务器，也不是套在 Docsy 外面的运行时包装层。Hugo 在构建阶段解析内容、配置、布局与资源，再生成可由普通文件托管服务发布的静态站点。

系统边界

flowchart LR
  C[站点内容] --> H[Hugo Extended]
  G[Hugo 配置] --> H
  T[Oink Hugo Module] --> H
  V[已提交的第三方资源] --> T
  H --> P[静态 public 目录]
  P --> B[浏览器]

消费端边界始于站点与已经解析的主题模块，止于 Hugo 生成的静态文件。在这条路径中，不需要 JavaScript 包管理器、CSS 后处理器可执行文件或远程资源下载。

交互功能仍会在浏览器中运行 JavaScript。“仅依赖 Hugo”描述的是构建依赖，并不意味着用户界面完全没有 JavaScript。

仓库边界

主题仓库

github.com/pgsty/oink 是公开 Hugo Module。仓库根目录包含标准布局、partial、短代码、SCSS、JavaScript、字体、图标、浏览器运行时、翻译资源、go.mod 与 hugo.yaml。VENDOR.json 记录随附的第三方资源。

该仓库不包含项目网站或 npm workspace。README.md、LICENSE、NOTICE、theme.toml 与 vendor 清单等根元数据，是发布和标注主题来源所必需的内容。

项目站点仓库

github.com/pgsty/oink.pgsty.com 包含文档、双语示例、回归页面、站点专用布局与资源、基于 npm 的站点测试，以及部署配置。它在 hugo.yaml 中导入公开主题模块，并在 go.mod 中固定版本。

贡献指南

Mon, 01 Jan 0001 00:00:00 +0000

OINK 是从 Docsy 派生的独立主题。贡献必须保留 Apache-2.0 历史和适用的第三方 NOTICE，同时改进唯一的标准实现。

提交变更之前

在 OINK 仓库中搜索已有 issue 和拉取请求。
报告缺陷时，请记录 Hugo 版本、安装方式、语言、路由、生产命令和最小可复现输入。
提议功能时，请说明它为什么属于可复用主题，而不是消费站点的业务层。
不要引入 oink.enabled 开关、oink.* 配置树或平行视觉外壳。OINK 的标准布局就是产品本身。

小型修复可以直接实现。较大的行为变更应在编写代码前说明兼容性、离线、无障碍、安全与迁移影响。

开发环境

消费站点只需要 Hugo Extended、Go 与 Git。主题仓库是直接的 Hugo Module；项目站点仓库使用固定的 Node.js 与 npm 版本运行格式、链接、翻译与回归检查。

请在仓库根目录按照 lockfile 安装维护依赖。不要在无关变更中顺带更新依赖。

项目拆分为：

github.com/pgsty/oink：发布主题源码与 VENDOR.json；
github.com/pgsty/oink.pgsty.com：文档、示例与测试。

构建消费端合同

必须从消费站点验证用户真正运行的路径：

BASH

hugo --gc --minify

该构建必须在消费站点不安装 npm 软件包的情况下成功，也不能为了主题自有浏览器资源发起网络请求。

测试本地主题候选版本时，把两个仓库克隆为同级目录，并启用被忽略的 Hugo workspace：

BASH

go work init .
go work edit -replace=github.com/pgsty/oink=../oink
HUGO_MODULE_WORKSPACE=go.work npm run build

运行聚焦测试

先选择最小的相关测试集：

开源许可与致谢

Mon, 01 Jan 0001 00:00:00 +0000

OINK 由采用 Apache 许可证的主题、单独授权的文档站，以及各自保留许可证的第三方组件组成。这些层次不会被重新授权成一份不加区分的作品。

本页用于帮助工程维护者理解来源，不代替许可证原文。如果摘要与许可证文件存在差异，以许可证文件为准。

许可证对应关系

范围	许可证	权威记录
Oink 主题源码与 Oink 的主题改动	Apache License 2.0	主题 `LICENSE` 与 `NOTICE`
站点代码、构建工具与源自 Docsy 的材料	Apache License 2.0	站点 `LICENSE` 与 `NOTICE`
Oink 原创文档，另有说明的内容除外	Creative Commons Attribution 4.0 International	`LICENSE-CC-BY-4.0`，以及页面或资源自己的署名说明
浏览器库、字体、图标与其他随主题分发的资源	各组件自己的许可证	主题 `VENDOR.json` 与随资源分发的许可证文件

Creative Commons 许可证适用于原创文档内容，不自动覆盖主题代码、复制的源码、商标、截图或另有声明的第三方资源。同样，主题采用 Apache-2.0，并不会替换随附依赖自己的许可证。

上游渊源

OINK 不是叠加在另一套 Docsy 安装之上的可选皮肤。继承而来的代码库已经演化成一套标准主题，提供仅依赖 Hugo 的消费端构建、本地浏览器运行时、多语言行为与独立发布流程。贡献者必须保留适用的上游声明，并按照 Apache-2.0 的要求标记修改过的文件。

Oink 依赖的项目

Hugo Extended 是构建平台。站点采用 Hugo Module 安装方式时由 Go 解析模块，Git 则承载源码与发布流程。这些工具属于前提条件，主题不会重新分发它们的可执行文件。

关于 Oink

Mon, 01 Jan 0001 00:00:00 +0000

OINK 把 Markdown、配置与本地资源转换成完整的技术文档站。站点取得主题源码并安装 Hugo Extended 后，无需维护前端工具链，即可构建文档、博客、多语言导航、本地搜索、图表、API 参考与可复用内容组件。

Oink 提供什么

能力	主题契约
文档与博客布局	响应式导航、面包屑导航、目录、页面元数据、反馈、打印与索引
多语言行为	译文路由、语言元数据、稳定锚点与分语言本地搜索
本地优先浏览器功能	固定版本的样式、字体、搜索、图表、API 参考、录像与信息图
内容组件	标签页、折叠块、步骤、卡片、轮播、图表、终端录像与参数替换
可复现交付	仅依赖 Hugo 的消费端构建、固定资源、vendor 清单与回归样例

OINK 把 Docsy 成熟的 Hugo 内容模型演化为独立主题，以 Hugo 作为构建平台，并从 Fumadocs 汲取设计灵感。开源许可页面分别说明上游传承、设计致敬、依赖与许可证，避免混淆这些关系。

了解这个项目

About 章节按照从评估到维护的顺序组织：

示例站点介绍完整双语项目站、主题自带的小型示例，以及创建最小消费站点的指南。
本地优先定义哪些构建与浏览器能力无需隐藏的网络访问。
架构解释仓库、构建、页面外壳、运行时与扩展边界。
贡献指南说明如何修改主题与双语文档。
开源许可说明项目渊源、依赖、致谢，以及站点与主题各自适用的许可证。

仓库边界

公开 Hugo Module 位于 github.com/pgsty/oink。文档、示例与回归测试位于独立的 github.com/pgsty/oink.pgsty.com 仓库。生产消费站点应固定已发布标签或不可变 commit。

站点自有的内容、品牌、配置与业务组件仍由站点控制。通用布局、可复用组件、本地浏览器运行时与翻译资源则属于主题。

从这里开始

安装 Oink，或创建双语站点；
阅读内容创作指南与高级特性；
阅读实现日志，了解设计决策与验证证据。

本地构建成功，只能证明某份源码在某个本地环境中能够渲染；它不能证明主题标签已经公开，也不能证明线上站点包含同一 commit。