使用 Oink 主题

• 1: 开始之前
• 2: 查看双语项目站点
• 3: 新建站点：从零开始

hugo --gc --minify

1 - 开始之前

消费端唯一必需的工具是 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。

项目站点仓库中的 Node 命令只供维护者使用。消费端的生产命令是：

hugo --gc --minify

检查完整发行物

用于离线或网络隔离环境时，请确认主题归档包含 go.mod、hugo.yaml、 assets/、layouts/、static/、i18n/、LICENSE、NOTICE 与 VENDOR.json。进入隔离环境前安装 Hugo Extended，然后在禁用网络的情况下运行同一个构建命令。

后续步骤

• 查看双语项目站点
• 从零创建站点
• 比较发行方式

2 - 查看双语项目站点

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

克隆项目站点

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 命令。

运行站点检查

Hugo 本身即可构建站点。Node.js 只用于项目站点的格式、链接、翻译与回归检查：

npm install
npm test

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

替换示例身份

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

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

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

替换示例内容

把每组译文放在一起：

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

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

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

## Configure search

## 配置搜索 {#configure-search}

将新站点纳入版本控制

发布派生站点前，请修改模块路径、仓库元数据与 remote。继续在 go.mod 中固定 Oink 版本。除非托管工作流有明确要求，否则不要提交生成的 public/ 产物。

后续步骤

• 查看基础配置。
• 学习内容组件。
• 配置部署。
• 使用发布检查清单。

3 - 新建站点：从零开始

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

创建站点骨架

运行：

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

添加双语内容

创建以下文件：

content/
├── _index.md
├── _index.zh.md
├── docs/
│   ├── _index.md
│   ├── _index.zh.md
│   ├── getting-started.md
│   └── getting-started.zh.md
└── blog/
    ├── _index.md
    └── _index.zh.md

每个页面都需要 front matter。例如，content/docs/getting-started.md 可以写成：

---
title: Getting started
weight: 10
---

## Install {#install}

Install the product.

它的 getting-started.zh.md 译文保留显式标题 ID：

---
title: 开始使用
weight: 10
---

## 安装 {#install}

安装产品。

在两个示例中使用相同的显式 ID 不会产生问题，还能直观展示跨语言合同。翻译现有页面时，应从英文渲染 HTML 中复制 ID。

预览与构建

启动开发服务器：

hugo server --disableFastRender

随后单独验证生产构建：

hugo --gc --minify

添加自定义布局前，请检查 /docs/、/zh/docs/、语言选择器、本地搜索索引和浏览器控制台。

逐步添加功能

先复制 Logo 和品牌素材，再添加代码仓库链接与菜单。只在确实需要的页面中加入图表、API 文档和内容组件；OINK 会按需发布对应的本地运行时。

如果站点需要带业务语义的短代码，请将其保留在站点自己的 layouts/_shortcodes/ 下。只有接口已经摆脱站点假设，并且能被多个站点复用后，才应移入主题。

后续步骤

• 扩展基础配置。
• 学习如何添加内容。
• 查看 OINK 架构。
• 选择部署目标。