使用 Oink 主题 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。

查看双语项目站点

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

独立的 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/ 产物。

新建站点：从零开始

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