快速上手 on OINK

开始之前

Wed, 08 Dec 2021 00:00:00 +0000

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

安装 Hugo Extended

安装 0.160.1 或更高版本。当前验证基线为 0.164.0。如果发布版本调整了这些数值，应以对应版本的支持矩阵为准。

核对实际选中的二进制文件：

hugo version

输出必须包含 extended；标准版 Hugo 无法编译主题的 SCSS。请根据平台使用 Hugo 官方安装指南，并在本地开发与 CI 中固定同一版本。

按需安装 Git

克隆站点、使用 submodule、保留 .GitInfo 或获取主题 checkout 时需要 Git。运行以下命令验证：

git --version

从已经解压的离线归档构建站点时，Hugo 可以在没有网络的情况下运行；不过仍建议使用版本控制管理源码。

只有 Hugo 模块需要 Go

Hugo 模块命令会使用 Go。如果站点以 Hugo 模块形式导入主题，请安装 Go 并运行：

go version
hugo mod graph

使用固定版本归档、相邻主题目录或 Git submodule 时，站点构建不需要 Go。

不要安装前端工具链

OINK 将 Bootstrap、Font Awesome、LTR 与 RTL CSS、字体、搜索和浏览器运行时作为有版本的本地资源提供。消费站点不需要为主题安装 Node.js、npm、PostCSS、Autoprefixer 或 RTLCSS。

安装 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.2.0 之类的已发布标签，或不可变的 commit。然后在 hugo.yaml 中添加导入：

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

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

预览站点

启动编辑服务器：

hugo server --disableFastRender

生成生产构建产物：

从零新建站点

Wed, 08 Dec 2021 09:21:54 +0100

独立的双语项目站点是完整参考。需要更小、拥有自身内容结构的站点时，可以采用本流程。

创建站点骨架

运行：

hugo new site --format yaml my-new-site
cd my-new-site

初始化站点模块并固定 Oink：

hugo mod init github.com/example/my-new-site
hugo mod get github.com/pgsty/oink@THEME_REF

添加最低配置

将以下内容保存为 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
  highlight:
    noClasses: false

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 管线。

站点基础配置

Wed, 08 Dec 2021 09:22:27 +0100

Hugo 从 hugo.yaml、hugo.toml 或 hugo.json 读取站点级设置。Oink 项目站点使用 YAML，因为多语言菜单和主题选项更便于浏览与评审。

最低配置

下面的节选展示了 Hugo Module 的关键结构。

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
  highlight:
    noClasses: false

params:
  offlineSearch: true
  github_repo: https://github.com/example/product-docs
  github_branch: main
  copyright:
    authors: Example Authors
    from_year: 2026
  ui:
    showLightDarkModeMenu: true
    sidebar_menu_foldable: true
    breadcrumb_disable: false

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

英文权重为 1，也是默认语言；简体中文权重为 2；其他语言依次排列。直接点击语言按钮时会按此顺序切换，完整的悬停菜单也采用相同顺序。

查看双语项目站点

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

独立的 pgsty/oink.pgsty.com 仓库是完整的双语示例与回归站点。它有意比最小消费站点更全面：应把它作为参考，然后只保留产品真正需要的内容与配置。

克隆项目站点

克隆项目站，即可使用其中固定的 Oink 公开版本完成构建：

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

已提交的 go.mod 会固定 github.com/pgsty/oink。本地开发主题时，请把主题克隆为同级目录，并使用 Oink 快速开始记录的 workspace 命令。

运行站点检查

使用 Oink 的站点无论构建还是预览，都不需要 Node.js，也不需要安装 npm 软件包。只有在维护这个示例项目站点仓库，并运行格式、链接、翻译与回归检查时，才需要 Node.js 以及仓库中的 npm 开发依赖：

npm ci
npm test

打开生成的站点，分别检查中英文页面。请从具有译文的详情页使用语言切换器，不要只在首页测试。

替换示例身份

编辑 hugo.yaml 与 config/ 下的文件，并替换：

站点标题，以及各语言的标题与描述；
baseURL；
代码仓库与分支 URL；
版权所有者与起始年份；
Logo 与品牌素材；
中英文菜单标签。

不要创建 oink.* 参数命名空间。请使用 Hugo 的语言、菜单、模块、输出和 markup 设置，以及主题已经记录的参数。

替换示例内容

把每组译文放在一起：

content/docs/getting-started.md
content/docs/getting-started.zh.md

删除产品不需要的历史与回归内容。只有在页面不再引用后，才删除对应示例资源。

中文标题应显式使用英文页面实际渲染出的 ID：

在容器中运行 OINK

Mon, 30 Jul 2018 00:00:00 +0000

容器并非必需：OINK 本身只需要 Hugo Extended。如果团队希望固定工具镜像，或不想在开发者工作站上安装 Hugo，可以选择容器方式。

创建 Hugo 镜像

下面的 Dockerfile 从发布包安装当前验证过的 Hugo Extended 版本。请让该版本始终与主题支持矩阵保持一致。

FROM debian:bookworm-slim

ARG HUGO_VERSION=0.164.0
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 \
    && rm -rf /var/lib/apt/lists/* /tmp/hugo.deb

WORKDIR /src
EXPOSE 1313
ENTRYPOINT ["hugo"]
CMD ["server", "--bind", "0.0.0.0", "--disableFastRender"]

在站点根目录构建镜像：

docker build -t oink-hugo .

镜像构建过程会下载 Hugo。在网络隔离环境中，请预先镜像基础镜像和 Hugo 软件包，或者将 OINK 完整离线发行包与获准使用的内部镜像组合使用。

预览站点

挂载完整站点源码，包括相邻存放或随站点提供的主题：

其他安装方式

Wed, 08 Dec 2021 00:00:00 +0000

推荐安装方式是使用 github.com/pgsty/oink Hugo Module。以下选项只改变 Hugo 获取同一份主题源码的方式，不会改变内容，也不会改变 Hugo-only 构建命令。

前提条件

所有方式都需要 Hugo Extended 0.160.1 或更高版本。Git 方式需要 Git，Hugo 模块需要 Go。消费站点采用任何一种方式都不需要 Node.js、npm、PostCSS 或 Autoprefixer。

选项 1：完整发布归档

完整离线归档包含主题、本地浏览器运行时、字体、许可证、NOTICE、vendor 清单和 checksum。它是网络隔离构建的首选输入，也是保留准确发行物最简单的方式。

把主题解压到站点的 themes/ 目录：

site/
├── hugo.yaml
└── themes/
    └── oink/

配置如下：

theme: oink

解压前先校验归档 checksum。只能使用明确发布版本附带的归档，不要把本地组装文件表述为已经发布的发行物。

选项 2：Git submodule

submodule 会在站点仓库中记录准确的 OINK 仓库 commit：

git submodule add https://github.com/pgsty/oink.git themes/oink
git -C themes/oink fetch --tags
git -C themes/oink checkout THEME_REF
git add .gitmodules themes/oink
git commit -m "Add OINK theme at THEME_REF"

配置嵌套主题路径：

故障排查与已知问题

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

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

hugo --gc --minify --logLevel info

消费端命令不应调用 npm、PostCSS、Autoprefixer，也不应下载主题浏览器资源。

构建问题

Hugo 不是 Extended 版本或版本过旧

运行 hugo version。输出必须包含 extended，版本也不得低于 0.160.1。如果 shell、编辑器、CI runner 或容器仍然选中了旧二进制文件，请检查它的 PATH 和固定工具配置，不要盲目再安装一份。

找不到主题

module "github.com/pgsty/oink" not found 一类错误表示 Hugo 无法解析配置中的主题。请按所选安装方式检查：

对于 Git checkout，主题名称必须与目录路径一致；
对于 Hugo 模块，运行 hugo mod graph，并检查 go.mod、go.sum，以及所有 Hugo workspace 或 replacement；
对于 CI checkout，请在运行 Hugo 前初始化固定版本的 submodule，或恢复完整发布归档。

缺少本地浏览器资源

如果缺少 Bootstrap、Font Awesome、Lunr、Mermaid 或其他 OINK 资源，不要通过添加 CDN URL 来掩盖问题。请确认发行物完整，并包含 assets/third_party/、assets/js/third_party/、static/webfonts/ 和 VENDOR.json。如果确有文件缺失，请重新解压或获取同一个固定版本。