教程 on OINK

环境准备

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

消费端唯一必需的工具是 Hugo Extended。是否还需要 Git 和 Go，取决于你用哪种方式获取主题。

安装 Hugo Extended

安装 0.160.1 或更高版本。项目站点当前的验证基线是 0.164.0。

按平台参照 Hugo 官方安装指南，装完之后核对实际选中的二进制：

BASH

hugo version

输出必须包含 extended：

CONSOLE

$ hugo version
hugo v0.164.0+extended+withdeploy darwin/arm64
                  ^^^^^^^^

标准版 Hugo 没有内置 Sass 编译器，无法编译主题的 SCSS，构建会直接失败。

本地开发和 CI 应该固定同一个 Hugo 版本。版本漂移导致的构建差异，排查成本远高于在 CI 里写死一个版本号。

什么时候需要 Git

以下场景需要 Git：

克隆站点仓库
用 submodule 或克隆方式获取主题
让 Hugo 读取 .GitInfo（页面的最后修改时间来自这里）

BASH

git --version

从已解压的离线归档构建时，Hugo 可以完全离线运行。不过源码本身仍然建议用版本控制管理。

快速上手

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

OINK 是一个把浏览器运行时随主题一起发布的 Hugo 主题。消费站点只需要 Hugo Extended：不装 Node.js、不跑 PostCSS、不依赖 CDN，构建期间也不会远程拉取主题资源。

这一章讲什么

按顺序读完这七页，你会得到一个可以部署的双语文档站：

环境准备 , 5 分钟: 装 Hugo Extended，确认版本带 extended 标记。Git 和 Go 是否需要取决于你怎么获取主题。
安装 OINK , 5 分钟: 推荐用 Hugo Module 固定一个版本。另外三种发行方式（离线归档、submodule、克隆）也在这一页。
创建站点 , 15 分钟: 从空目录到第一个可预览的页面，包含双语内容的组织方式。
基础配置 , 20 分钟: 站点身份、语言、搜索、仓库链接、生产构建参数。
项目站点 , 可选: 直接拿 oink.pgsty.com 当模板改，适合给开源项目快速起一个文档站。
容器预览 , 可选: 不在本机装 Hugo，用容器跑预览和生产构建。
故障排查 , 备查: 构建、语言、搜索、平台四类常见问题的定位方法。

三条起步路径

你的情况	建议路径
全新项目	环境准备 → 安装 → 创建站点
已有 Hugo 站点	直接看安装，把 OINK 作为模块导入
已有 Docsy 站点	看从 Docsy 迁移，正文不用重写

最短路径

如果你已经装好 Hugo Extended、Git 和 Go，三条命令就能跑起来：

安装 OINK

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

OINK 以 Hugo Module github.com/pgsty/oink 发布。推荐所有站点使用模块方式——它是唯一能让 Hugo 自己解析版本、校验 checksum、并在 go.sum 里留下审计记录的方式。

另外三种方式面向特定约束：网络隔离、平台要求完整源码树、或者组织内部需要评审主题副本。它们都在其他安装方式一节。

前置条件

模块方式需要 Git、Go 和 Hugo Extended 0.160.1 或更高版本：

BASH

git --version
go version
hugo version

hugo version 的输出必须包含 extended。标准版 Hugo 无法编译主题的 SCSS，会在构建时报错。

详细的平台安装说明见环境准备。

添加模块

在站点根目录初始化模块（如果还没有），然后固定一个 OINK 版本：

BASH

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

在 hugo.yaml 中导入：

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

提交生成的 go.mod 与 go.sum。

创建站点

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

这一页从零建一个最小双语站点。如果你想要一个已经配置完整的参考，直接看项目站点。

建立骨架

BASH

hugo new site --format yaml my-docs
cd my-docs
hugo mod init github.com/example/my-docs
hugo mod get github.com/pgsty/oink@v0.4.1

最小配置

把下面的内容存为 hugo.yaml。这是能跑起来的最小集合，逐项含义见基础配置：

title: Product Docs
baseURL: https://docs.example.com/
defaultContentLanguage: en

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

markup:
  goldmark:
    renderer:
      unsafe: true

params:
  offlineSearch: true
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true

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

提交 go.mod 与 go.sum。不要添加 npm 挂载或 PostCSS 管线。

基础配置

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

Hugo 从 hugo.yaml、hugo.toml 或 hugo.json 读取站点级设置。OINK 项目站点用 YAML，因为多语言菜单和主题选项以 YAML 形式更好读、也更好评审。

这一页覆盖让站点跑起来所必需的配置。导航菜单、多语言细节和版本管理见站点配置。

完整最小配置

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

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 }

markup:
  goldmark:
    renderer:
      unsafe: true

params:
  offlineSearch: true
  github_repo: https://github.com/example/product-docs
  github_branch: main
  copyright:
    authors: '[Example Authors](https://example.org/)'
    from_year: 2026
  footer_center_info: 'Powered by [Oink](https://oink.pgsty.com)'
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true

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

关键参数

baseURL , string , required: 生产环境的真实地址，包含子路径。部署到 example.com/docs/ 时必须写成 https://example.com/docs/，否则所有资源链接都会指向错误位置。

用项目站点起步

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

pgsty/oink.pgsty.com 是 OINK 的双语示例兼回归站点。它有意比一个最小消费站点更完整——把它当参考，然后删掉产品用不到的部分。

适合这条路径的情况：你想要一个开箱即用的双语结构，不介意先删再改。想从零精确控制每一项，走创建站点。

克隆并构建

BASH

git clone https://github.com/pgsty/oink.pgsty.com.git product-docs
cd product-docs
hugo --gc --minify

已提交的 go.mod 固定了 github.com/pgsty/oink 的公开版本，所以克隆下来就能构建。

如果你同时要改主题，把主题克隆为同级目录，用安装页记录的 workspace 命令。

站点检查需要 Node

这一点容易误解：使用 OINK 构建站点不需要 Node.js。只有维护这个示例仓库、运行格式化/链接/翻译/回归检查时才需要：

BASH

npm ci
npm test

你自己的产品文档站不需要继承这套工具链。

替换示例身份

编辑 hugo.yml，替换这些字段：

title / languages.<lang>.title , string: 站点名称，各语言分别设置。
baseURL , string: 换成你自己的生产地址。
params.github_repo , string: 指向你自己的内容仓库，否则「编辑此页」会指向 OINK 的仓库。
params.copyright , string | map: bottom bar 中兼容 Docsy 的作者与年份范围。

容器化预览

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

容器不是必需的——OINK 只要求 Hugo Extended。适合用容器的情况：团队要固定工具链版本，或者不想在每台开发机上装 Hugo。

构建镜像

FROM debian:bookworm-slim

ARG HUGO_VERSION=0.164.0
ARG GO_VERSION=1.25.5
ARG TARGETARCH

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl git \
    && curl -L -o /tmp/hugo.deb \
      "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-${TARGETARCH}.deb" \
    && apt-get install -y /tmp/hugo.deb \
    && curl -L -o /tmp/go.tgz \
      "https://go.dev/dl/go${GO_VERSION}.linux-${TARGETARCH}.tar.gz" \
    && tar -C /usr/local -xzf /tmp/go.tgz \
    && rm -rf /var/lib/apt/lists/* /tmp/hugo.deb /tmp/go.tgz

ENV PATH="/usr/local/go/bin:${PATH}"
WORKDIR /src
EXPOSE 1313
ENTRYPOINT ["hugo"]
CMD ["server", "--bind", "0.0.0.0", "--disableFastRender"]

BASH

docker build -t oink-hugo .

镜像里装了 Go。如果站点用 Hugo

Module 方式引入主题，这一步不能省——Hugo 需要 Go 才能解析和下载模块。用离线归档、submodule 或克隆方式的站点可以去掉 Go，镜像会小很多。

故障排查

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

诊断从一次干净的生产构建开始：

BASH

hugo --gc --minify --logLevel info

消费端的构建命令不应该调用 npm、PostCSS 或 Autoprefixer，也不应该下载主题的浏览器资源。如果日志里出现这些，说明配置里混进了上游 Docsy 的流程。

构建问题

Hugo 不是 Extended 版本或版本过旧

BASH

hugo version

输出必须包含 extended，版本不低于 0.160.1。

如果 shell、编辑器、CI runner 或容器仍然选中旧二进制，先查 PATH 和工具版本固定配置，不要盲目再装一份——多个 Hugo 共存会让问题更难定位。

找不到主题

module "github.com/pgsty/oink" not found 说明 Hugo 无法解析主题。按安装方式排查：

安装方式	检查项
Hugo Module	`hugo mod graph`，以及 `go.mod`、`go.sum`、是否存在 workspace 或 replace
Git submodule	CI 是否在跑 Hugo 前执行了 `git submodule update --init`
归档 / 克隆	`theme:` 的值是否与 `themes/` 下的目录名一致

缺少本地浏览器资源

Bootstrap、Font Awesome、Lunr、Mermaid 等资源缺失时，不要加 CDN URL 来掩盖。确认发行物完整，应包含：