仓库导览

本页逐项说明 pgsty/oink.pgsty.com 克隆下来的每个文件与目录：哪些必须保留、哪些替换为你自己的信息、哪些是文档站自用可以整棵删除，并给出一个安全的删除顺序。

主题代码不在这个仓库里：它是 go.mod 固定的一个 Hugo Module，存放在 Go 的模块缓存中。这个仓库只有内容、配置与站点自己的少量覆盖。

顶层结构

上面没有列出的还有 .gitignore、.gitattributes、.nvmrc、.npmrc，以及被 .gitignore 排除的生成物：public/（构建产物）、resources/（Hugo 资源缓存）、node_modules/。后一组不进版本库。

仓库里没有 i18n/：界面文字（「上一页」「本页目录」这类）由主题的 32 份语言文件提供。要改其中某一句，在站点根目录建 i18n/zh.yaml，只写需要覆盖的键。

各项的处理方式

删除顺序

顺序是先删外围、再删内容、最后清数据。每删一步构建一次，出问题时能定位到具体步骤。

1. 删脚手架

   这一批与站点渲染无关，删除后不影响任何页面。

   rm -rf tests scripts node_modules
   rm -f package.json package-lock.json playwright.config.mjs .nvmrc .npmrc
   rm -f AGENTS.md TRANSLATION.md CONTRIBUTING.md agent-docs.config.yml Makefile
   rm -f .github/workflows/site-checks.yml .github/workflows/browser-quality.yml

   删除 scripts/ 之后必须改 .github/workflows/pages.yml：把 Set up Node.js 与 Verify advertised and pinned release match 两步删掉，否则部署会在该步骤失败。

2. 删示例内容

   content/docs/ 是 OINK 自己的主题文档，content/blog/ 是它的工程博客，与你的产品无关。

   rm -rf content/docs
   mkdir -p content/docs
   rm -rf content/blog        # 不要博客的话；要的话只留一篇当模板

   同时改 hugo.yml 里每种语言下的 menus.main：那些菜单项指向 /docs/tutorial、/blog/release 这些已不存在的路径。content/_index.md 是首页，保留它，把正文换成你的。

3. 清数据

   data/ 下三组数据分别供首页、Landing 页与发布页使用。首页数据保留后修改，另外两组用不到就删除。

   rm -rf data/landing data/download

   data/home/en.yaml 与 data/home/zh.yaml 决定首页有哪些分区，逐项含义见首页与落地页。删除整个 data/home/ 也能构建，首页退回为普通内容页。

4. 换身份

   最后把 hugo.yml 里的站名、params.productionURL、params.github_repo 与品牌参数换成你的，替换 static/ 下的 logo 与 favicon，删掉 services.googleAnalytics、params.comments 与 params.version* 这些 OINK 专用配置。逐条清单见十分钟上手第 3 步。

主题的位置

主题以 Hugo Module 的形式引用，两处配置指向它：

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

require github.com/pgsty/oink v0.6.0

hugo.yml 声明使用哪个主题，go.mod 固定用它的哪一版，go.sum 记录该版本的校验和。三个文件都要提交。主题源码不进你的仓库：Hugo 把它下载到 Go 的模块缓存，hugo mod graph 显示实际解析结果。

升级到最新版：

hugo mod get -u github.com/pgsty/oink

固定到某一个版本：

hugo mod get github.com/pgsty/[email protected]

两条命令都会改写 go.mod 与 go.sum。生产站点固定到发布标签，不要跟随 main。升级前后检查什么、如何回滚，见版本升级。

站点覆盖

layouts/ 下的文件按 Hugo 的模板查找顺序盖过主题里的同名文件。本站只放了一类：

• layouts/_shortcodes/*.html：站点自己的 shortcode。产品文档需要带业务语义的 shortcode 时也放这里。

标题自链锚点由主题的 _markup/render-heading.html 提供，站点不需要自己建这个钩子。

要改外壳（侧栏、页脚、页尾）时，覆盖最窄的那个 partial，不要整份复制 baseof.html：复制之后每次主题升级都要手工合并。

验证

每删一步运行一次构建，报错能定位到刚删除的内容：

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

删除完成后，这几条应当成立：

• 构建以 Total in … 结束，没有 WARN / ERROR
• 顶栏菜单没有指向已删目录的死链
• 标题右侧仍然有自链锚点（主题自带的标题渲染钩子，站点不需要覆盖）
• git status 里没有 public/、resources/

相关

• 十分钟上手 — 克隆、改配置、部署的完整流程
• 从零建站与其它安装方式 — 从空目录搭建，不做删减
• 组织内容 — content/ 的目录结构怎么变成侧栏
• 配置总览 — hugo.yml 每个键的含义与默认值
• 版本升级 — 升级主题模块与迁移工具