OINK on OINK 文档主题

快速开始

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

Oink 以 Hugo Module github.com/pgsty/oink 发布。消费站点只需 Hugo Extended 即可构建；Node.js、npm、PostCSS 和 CDN 托管的浏览器软件包不属于构建契约。

前置条件

安装 Git、Go 与 Hugo Extended 0.160.1 或更高版本。项目站点目前使用 0.164.0 验证：

git --version
go version
hugo version

Hugo 版本输出必须包含 extended。

添加模块

在 Hugo 站点根目录中，如果站点还没有模块，先初始化模块，再固定一个 Oink 版本：

hugo mod init github.com/example/product-docs
hugo mod get github.com/pgsty/oink@THEME_REF

请把 THEME_REF 替换为 v0.16.0 之类的已发布标签，或不可变的 commit。然后在 hugo.yaml 中添加导入：

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

提交生成的 go.mod 与 go.sum。生产构建不要跟随未固定版本的分支。

预览站点

启动编辑服务器：

架构

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 的本地优先原则很简单：由主题提供的功能，不得暗中依赖公共 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 把已经在多个 PGSTY 站点证明具有复用价值的内容组件纳入主题。每个组件都有稳定的作者接口、唯一实例 ID、本地资源和明确的安全边界。站点专用的数据控件仍然留在主题之外。

加载模型

交互式短代码会标记页面实际使用的功能。OINK 随后为每个所需样式或运行时只加入一次，即使页面中存在多个组件实例也不例外。普通页面不会下载从未使用的组件代码。

相对资源与链接参数会经过 Hugo URL 处理，因此部署到 baseURL 子路径时仍然正确。在适用情况下，组件标记还覆盖打印、深色模式、移动端、键盘操作与减少动态效果偏好。

Asciinema

使用 asciinema 播放保存在本地的 .cast 终端录像：

{{< asciinema
  file="oink/demo.cast"
  speed="1.5"
  markers="0:开始,1:完成"
>}}

file 是必填参数，也可以作为第一个位置参数传入。支持的选项包括 theme、fit（width、height、both 或 none）、autoplay、loop、 preload、speed、startAt、poster、cols、rows、idleTimeLimit、 pauseOnMarkers，以及逗号分隔的 markers。

为了离线使用，请把 cast 文件保存在本地。只有作者显式提供远程 URL 时，组件才会访问远端。

ECharts

默认安全模式接受 JSON 或 YAML，并把解析后的值序列化到 application/json 元素中：

{{< echarts height="280px" >}}
xAxis: { type: category, data: [源码, 构建, 发布] }
yAxis: { type: value }
series: [{ type: bar, data: [1, 2, 3] }]
{{< /echarts >}}

height 默认为 400px，并且必须使用安全的 CSS 长度单位。theme 用来选择 ECharts 主题，full=true 则移除通常的正文宽度限制。

配置

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

OINK 遵循“原生优先”的配置模型。站点身份、语言、菜单、输出、taxonomy、标记与模块继续放在 Hugo 规定的位置；语义仍然适用的 Docsy 参数也保持原位。只有无法可靠推导的行为选择，OINK 才会增加职责明确的配置。

配置原则

优先使用 Hugo 配置，不创建主题专用的重复项。
优先使用成熟的 Docsy 参数，不另造 OINK 同义词。
品牌、内容、仓库与 UI 选项应放在各自语义位置。
内部 vendor 路径与模板组装方式不属于公开 API。
遇到非法值或缺少必需端点时，应尽早失败。

OINK 不提供 oink.enabled 开关，也不建立 params.oink.* 配置树。增加这些配置会制造第二套主题模式，让每项修复、测试和文档都产生歧义。

完整基线配置

以下示例把英文设为首要语言、简体中文设为第二语言：

title: Product Documentation
baseURL: https://docs.example.com/
defaultContentLanguage: en
enableRobotsTXT: true

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    menus:
      main:
        - { name: Docs, pageRef: /docs, weight: 10 }
        - { name: Blog, pageRef: /blog, weight: 20 }
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    menus:
      main:
        - { name: 文档, pageRef: /docs, weight: 10 }
        - { name: 博客, pageRef: /blog, weight: 20 }

outputs:
  home: [HTML]
  section: [HTML, RSS, print]

markup:
  goldmark:
    renderer:
      unsafe: true
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
  highlight:
    noClasses: false

params:
  logo: icons/logo.svg
  offlineSearch: true
  offlineSearchIndex: summary
  offlineSearchMaxResults: 10
  github_repo: https://github.com/example/product-docs
  github_branch: main
  footer_icp: ''
  footer_icp_url: https://beian.miit.gov.cn/
  copyright:
    authors: Example Authors
    from_year: 2026
  ui:
    showLightDarkModeMenu: true
    quick_links: [docs, blog]
    sidebar_menu_foldable: true
    sidebar_item_overflow: wrap
    breadcrumb_disable: false

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

模块版本固定在站点的 go.mod 中。使用传统主题 checkout 时，可以把仓库放在 themes/oink/，并改用 theme: oink。

部署

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

OINK 部署包含两个独立阶段：Hugo 先生成完整的 public/ 目录，静态托管服务再发布该目录。请把构建验证与线上验证分开，避免把一次成功的本地命令误认为已经完成生产发布。

生产构建

在站点根目录使用固定版本的 Hugo Extended 运行：

hugo --gc --minify --cleanDestinationDir

--gc 会清理不再使用的缓存资源，--minify 生成生产资源，--cleanDestinationDir 删除上次构建残留的文件。如果 publishDir 不是站点专用输出目录，使用最后一个参数前必须先检查命令目标。

构建应顺利完成，并且不能用忽略告警的方式掩盖缺失内容、端点或资源。上传前请先在本地检查 public/。

本地预览

编辑期间运行：

hugo server --disableFastRender

Hugo 开发服务器只能证明源码可以渲染；它不是生产托管服务，实时重载行为也不属于生成后的站点。每次发布前都应执行一次干净的生产构建。

静态托管

任何能够提供目录和文件的主机都可以发布 OINK：

对象存储与 CDN；
GitHub Pages、GitLab Pages 或类似的 Git 驱动静态托管；
Netlify、Cloudflare Pages 或其他构建并发布的平台；
Nginx、Caddy、Apache 或内部文件服务器。

请把 baseURL 设置为生产环境 canonical URL。如果站点发布在 https://example.com/manual/ 之类的子路径下，应包含该路径并进行测试；OINK 的本地资源与组件 URL 设计为支持子路径部署。

Cloudflare Pages

让 Pages 直接连接源分支。OINK 不需要由 GitHub Actions 预先构建并推送孤立 Pages 分支。

迁移现有站点

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

OINK 旨在替换各站点复制的公共外壳、运行时与短代码，而无需批量重写普通正文。安全迁移应按依赖关系删除覆盖项，把产品专用行为留在站点，并在修改生产环境前先验证临时副本。

迁移原则

固定目标实现，不要把生产站点迁移到未固定版本的分支。
删除覆盖项之前先完成清点。
删除公共主题副本，不删除站点业务逻辑。
在 OINK API 兼容的地方，保持内容 URL、front matter 与短代码行为不变。
unsafe 或在线例外必须显式声明，并且只在过渡期使用。
分别测试构建产物、浏览器行为与托管站点行为。

固定目标版本

请在 go.mod 中固定已发布标签，或使用完整的版本化归档。预发布评估期间，Hugo Module 站点可以使用被忽略的 Go workspace，在不修改已提交模块版本的情况下解析本地 checkout：

go work init .
go work edit -replace=github.com/pgsty/oink=/absolute/path/to/oink
export HUGO_MODULE_WORKSPACE=go.work
hugo --gc --minify

站点的 hugo.yaml 导入 github.com/pgsty/oink；workspace 只替换本地 checkout。

清点现有覆盖项

把每个站点级文件归入以下四类之一：

类别	处理方式
公共外壳的完全或近似副本	OINK 验证通过后删除
OINK 已提供的可复用组件	删除或机械重命名
范围明确的品牌或产品定制	保留，再缩小到最小 hook
业务专用数据或交互	留在站点

layouts/、assets/、static/、配置与构建工作流必须一起检查。复制的短代码通常还伴随一份 JavaScript bundle、样式表、vendor 文件和 CI 安装步骤。

发布流程

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

Oink 把实现、验证、公开发布与部署视为不同状态。一次绿色本地构建是有价值的证据，但它不是公开标签、可下载模块，也不是已经部署的文档更新。

发布状态

状态	必需证据
源码完成	范围、文档、变更日志、归属信息与评审全部完成
验证完成	主题模块与项目站点检查通过
公开发布	`pgsty/oink` 中存在不可变根标签，并可通过 Go 解析
文档完成	`pgsty/oink.pgsty.com` 固定并记录该标签
部署完成	托管文档与目标消费站点通过验证

应报告准确状态与证据；不要把本地构建称为发布。

版本管理

主题版本在 github.com/pgsty/oink 使用 vX.Y.Z 这样的根标签。主题现在就是仓库根模块，因此不再使用嵌套的 theme/vX.Y.Z 标签。

项目站点的 version 参数标识发布的站点变体，不会自动成为 Git ref。安装说明与 go.mod 必须使用真实可解析的主题标签。

验证主题仓库

从干净的 pgsty/oink checkout 开始：

检查源码 diff 与归属信息变更；
验证 VENDOR.json 中每个文件与 SHA-256；
确认仓库没有生成的 public/、资源缓存、node_modules/ 或内嵌 example site；
使用最低版本与当前支持版本的 Hugo Extended，通过 Hugo Module 路径构建最小消费站点；
检查 module zip，确认布局、资源、翻译、静态文件、许可证与 NOTICE 都存在。

module zip 测试很重要，因为 Go 会从发布模块中排除 vendor 等特殊目录名。Oink 把随附依赖放在 assets/third_party/，确保它们能进入模块发行物。