开始使用 on 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"

配置嵌套主题路径：

在容器中运行 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 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

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

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。如果确有文件缺失，请重新解压或获取同一个固定版本。