十分钟上手

这条路径不从空目录开始，而是克隆你正在读的这个站点，删掉不需要的部分，再替换成你自己的信息。本站是 OINK 的回归站，包含每个组件与每种页面类型，并与主题保持同版本；从它开始删减，比从空目录逐项补配置与示例少写很多。

前提：一台能安装 Hugo Extended 与 Go 的机器、一个 GitHub 账号、十分钟。不需要 Node.js，也不需要其它前端工具链。

结果

完成后得到一个双语文档站：左侧栏是你的目录树，右侧是本页目录，顶栏有全文搜索与命令面板，深浅色跟随系统；一份 Markdown 同时产出网页、打印页、纯 Markdown 与 RSS；托管在 GitHub Pages 上。

步骤

1. 安装 Hugo Extended 与 Go

   除 Git 之外需要两样。Hugo Extended 必须是 0.160.1 或更高版本：标准版 Hugo 没有内置 Sass 编译器，编译不了主题样式，构建失败。Go 用于解析模块：OINK 以 Hugo Module 发布，Hugo 通过 Go 的模块机制下载并校验 github.com/pgsty/oink。

   macOS

   brew install hugo go git

   Linux

   # 发行版仓库里的 Hugo 往往过旧，改用官方 deb 包（本站 CI 也是如此）
   curl -LO https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.deb
   sudo dpkg -i hugo_extended_0.164.0_linux-amd64.deb
   sudo apt install -y golang-go git

   Windows

   winget install Hugo.Hugo.Extended
   winget install GoLang.Go
   winget install Git.Git

   安装完成后核对一次，输出里必须出现 extended：

   $ hugo version
   hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z
   $ go version
   go version go1.26.6 darwin/arm64
   

   其它平台按 Hugo 安装指南 与 go.dev/dl 安装，注意选 extended 版本。

2. 克隆文档站并预览

   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs
   hugo server

   打开 http://localhost:1313/，中文站在 http://localhost:1313/zh/。第一次启动会下载主题模块（几秒到一分钟，取决于网络），之后修改文件是毫秒级热重载。

   已提交的 go.mod 固定了主题版本，克隆之后即可构建，不需要额外的安装脚本。

   说明

   仓库里的 Makefile 只是几条命令的别名。make dev 与 make check 通过 HUGO_MODULE_REPLACEMENTS 使用同级的 ../oink 主题 checkout；make build 与 make serve 始终使用 go.mod 固定的公开版本。新站点用 hugo server 即可。

3. 替换站点信息

   站点身份：全部在 hugo.yml 里。baseURL 用的是 YAML 锚点，实际地址写在 params.productionURL 上，只改这一处：

   hugo.yml

   title: Product Docs # 顶栏站名与 <title>
   
   params:
     productionURL: &productionURL https://docs.example.com/
     github_repo: https://github.com/example/product-docs # 「编辑当前页面」指向哪
     copyright:
       authors: '[Example Inc.](https://example.com/)'
       from_year: 2026
     footer_center_info: ''
   
   baseURL: *productionURL

   languages.en.title 与 languages.zh.title 会覆盖顶层 title，两处一起改。参数逐项的含义与默认值见配置总览。

   删掉本站专用的配置：保留它们会让你的站点指向 OINK 的仓库与账号。

   hugo.yml 里的键	怎么处理
   services.googleAnalytics.id	OINK 的统计 ID，删掉；需要统计时换成你自己的
   params.comments	giscus 指向 pgsty/oink.pgsty.com 的讨论区，整段删掉或换成你的仓库
   params.tdVersion params.version params.version_menu params.versions	OINK 的版本菜单，删掉
   params.github_project_repo	主题仓库链接，删掉
   languages.<lang>.menus.main	顶栏菜单指向 /docs/tutorial 这类本站栏目，按你的目录重写

   换 Logo 与图标：替换这三个文件，文件名保持不变，主题按文件名挂载：

   static/

   static/favicon.svg           # 浏览器标签页图标
   static/favicon.ico
   static/apple-touch-icon.png  # iOS 添加到主屏

   static/logo.svg 是本站自己的品牌组合标，没有参数指向它：删掉，或者换成你的横向字标再设 params.wordmark。

   替换内容：content/docs/ 是 OINK 自己的主题文档，整棵删除，写你自己的第一页：

   rm -rf content/docs && mkdir -p content/docs

   content/docs/_index.md

   ---
   title: Docs
   linkTitle: Docs
   description: Product documentation.
   weight: 20
   ---
   
   Everything about running Product in production.

   content/blog/ 可以留一篇当模板，也可以整个目录删除（删除后把 menus.main 里的 blog 项一并删掉）。哪些目录必须保留、哪些是文档站自用，见仓库导览。

   只做英文站：删除 languages.zh 整段与所有 .zh.md 文件，languages 缩成一段：

   hugo.yml

   defaultContentLanguage: en
   languages:
     en:
       label: English
       locale: en-US
       weight: 1
       title: Product Docs
       menus:
         main:
           - { name: Docs, pageRef: /docs, weight: 20 }

   find content -name '*.zh.md' -delete

   保留双语或换成其它语言对，见多语言。

4. 部署

   在 GitHub 上新建一个空仓库，把本地历史换成你自己的：

   rm -rf .git && git init -b main
   git add . && git commit -m "Initial documentation site"
   git remote add origin [email protected]:example/product-docs.git
   git push -u origin main

   仓库自带 .github/workflows/pages.yml：推到 main 分支即构建并发布，也可以在 Actions 页面手动触发（workflow_dispatch）。它固定 Hugo Extended 与 Go 的版本，用 --printPathWarnings --panicOnWarning 构建，baseURL 由 GitHub Pages 提供，因此发布到 example.github.io/product-docs/ 这类子路径也不必改配置。

   在仓库的 Settings → Pages → Build and deployment → Source 选 GitHub Actions。默认值是 Deploy from a branch，不改这一项 workflow 会在部署步骤失败。

   删除 scripts/ 后要改 workflow

   pages.yml 中的 Verify advertised and pinned release match 一步运行 node scripts/check-release-pin.mjs，校验站点公告的版本与 go.mod 固定的版本一致。删掉 scripts/ 之后，把这一步与 Set up Node.js 一并从 pages.yml 移除。

   Cloudflare Pages、Netlify、Nginx 与离线打包见发布上线：构建命令都是 hugo --gc --minify，区别只在 baseURL 与环境变量。

验证

本地运行一次生产构建。它比开发服务器严格，路径告警会让构建失败：

hugo --gc --minify --printPathWarnings --panicOnWarning

输出 Total in … 且没有 WARN / ERROR 即通过。再对照预览核对：

• 顶栏是你的站名与 Logo，浏览器标签页是你的 favicon
• 侧栏是你自己的目录树，每页都能打开
• 按 Ctrl+ 加 K（macOS 上是 ⌘+ 加 K）打开命令面板，能搜到刚写的页面
• 页面标题右侧的菜单里，「编辑当前页面」指向你自己的仓库，不是 pgsty/oink.pgsty.com
• 部署后 GitHub 仓库 Actions 页面里的 Deploy Oink site to GitHub Pages 是绿的

构建报错见排错与检查。

下一步

• 仓库导览 — 克隆下来的每个目录是什么，哪些可以删。
• 编写页面 — 一页文档的组成：front matter、标题锚点、链接与图片。
• 组件总览 — 提示块、标签页、参数表、文件树等，每个组件一页。
• 品牌外观 — 主色、字体预设、页宽与自定义样式。
• 发布上线 — GitHub Pages 之外的托管方式与验收清单。

给编码助手的指令

上面四步可以交给编码助手（Claude Code、Codex 等）执行。复制下面这段指令，把方括号里的三处替换为你自己的信息：

请帮我用 OINK 主题建一个文档站，按下面的流程做，遇到不确定的地方按「只在缺信息时问人」处理。

1. 检查环境：运行 `hugo version`，要求输出包含 `extended` 且版本 >= 0.160.1；运行 `go version`，
   要求能拿到版本号。任一不满足就先按官方文档安装，macOS 用 `brew install hugo go`，
   Debian/Ubuntu 装 GitHub Releases 上的 hugo_extended deb 包。
2. 克隆站点模板：`git clone https://github.com/pgsty/oink.pgsty.com [目标目录]` 并进入该目录。
3. 改 hugo.yml 三处：顶层 `title` 与 `languages.<lang>.title` 改成 [站点名称]；
   `params.productionURL` 改成 [站点域名]（baseURL 是指向它的 YAML 锚点，不要单独改 baseURL）；
   `params.github_repo` 改成本站将来的仓库地址。
   同时删掉这些本站专用配置：`services.googleAnalytics`、`params.comments`、
   `params.tdVersion`、`params.version`、`params.version_menu`、`params.versions`、
   `params.github_project_repo`，并把 `menus.main` 改成只指向 /docs 与 /blog。
4. 清空示例内容：删除 `content/docs/` 整棵目录，新建 `content/docs/_index.md`
   （front matter 至少有 title / description / weight）；`content/blog/` 下只保留一篇文章当模板。
   删除文档站自用的脚手架：`tests/`、`scripts/`、`playwright.config.mjs`、`package.json`、
   `package-lock.json`、`AGENTS.md`、`TRANSLATION.md`、`CONTRIBUTING.md`、`agent-docs.config.yml`，
   并把 `.github/workflows/` 下除 `pages.yml` 外的 workflow 删掉，
   同时删掉 `pages.yml` 里的 `Set up Node.js` 与 `Verify advertised and pinned release match` 两步。
5. 后台启动 `hugo server`，确认 http://localhost:1313/ 返回 200 且页面标题是新站点名。
6. 校验：运行 `hugo --gc --minify --printPathWarnings --panicOnWarning`，
   要求以 `Total in ...` 结束且没有 WARN/ERROR；有报错就修到通过，不要用忽略告警的方式绕过。
7. 只在缺少 [站点名称]、[站点域名]、仓库地址这三项信息时才问我，其余按上面的默认做法执行。

建好的站点便于助手读取：每页都有 .md 纯文本输出，站点根有 llms.txt，页面标题右侧的菜单里有「复制 Markdown 文本」与「在 Claude 中打开」。见 Agent 支持。

不从这个仓库起步、要从空目录搭建，见从零建站与其它安装方式。

相关

• 仓库导览 — 每个目录是什么、删的顺序
• 从零建站与其它安装方式 — hugo mod init 起步、submodule 与离线安装
• 本地预览 — hugo server 的常用开关与草稿预览
• 发布上线 — 各家托管的配置与验收清单
• 排错与检查 — 构建、语言、搜索、平台四类常见错误