排错与检查

出问题时先做一次干净的生产构建，从第一条错误开始看，后面的多半是级联结果：

rm -rf public resources/_gen
hugo --gc --minify --printPathWarnings --panicOnWarning --logLevel info

日志里出现 npm、PostCSS、Autoprefixer 或下载浏览器资源的步骤，说明配置里混进了上游 Docsy 的流程。OINK 消费端的构建只有一条 Hugo 命令。

下面四张表按「症状 → 原因 → 修法」组织，找到症状那一行即可，不必从头读。

构建

那三项 goldmark 配置：

markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false
      attribute:
        block: true
    renderer:
      unsafe: true

两个最常见的 shortcode 报错长这样，注意结尾的 文件:行:列：

ERROR error building site: assemble: failed to create page from pageMetaSource /a:
  "…/content/docs/x.md:4:1": failed to extract shortcode:
  shortcode "tabs" must be closed or self-closed

ERROR error building site: assemble: failed to create page from pageMetaSource /a:
  "…/content/docs/x.md:4:5": failed to extract shortcode:
  template for shortcode "tabs" not found

语言

搜索

平台

站点自带检查

除了构建本身，站点还可以自己跑这几项。前两条任何 OINK 站点都能用，后面几条是本仓库的 npm 脚本，其它站点跑等价的检查即可。

npm test 里的六项各管一段：

• test:base — 先构建一次，再跑 Markdown 风格、翻译对等、渲染后的 Markdown 与链接检查。
• test:hugo-build — 构建断言：博客元数据、RSS、内容组件、构建过程零弃用提示。
• test:md-output — Markdown 与 llms.txt 输出的 golden 比对，字节级。改了组件的 Markdown 形态就会在这里挂。
• test:alt-site — 用 tests/fixtures/*.yml 里的替代配置各构建一次，确认不同配置组合都能起来。
• test:favicons — head 输出的 golden 比对。
• test:release-pin-contract — 站点公告的版本与 go.mod 固定的版本是否一致。

浏览器行为另开一套：npm run test:browser 依次跑 Playwright 的无障碍（axe WCAG AA）、响应式外壳、键盘导航、内容组件、代码块与场景组件六个套件。

诊断习惯

上面的表覆盖不到的问题，按这几条挖：

• 用固定的 Hugo Extended 版本复现，不在版本浮动的环境里判断。
• 清掉 public/ 与 resources/_gen 再重建，排除陈旧缓存。
• 对比开发与生产两套配置层，很多只在线上出现的问题是环境差异。
• 看第一条错误，不是最后那条。
• 用一个最小页面区分「主题行为」和「站点覆盖」：把可疑内容单独放一页，站点覆盖分批重新启用，定位到具体那一项。
• 看故障页面的浏览器控制台与网络面板，尤其是 404 的资源路径。

求助渠道

开 issue 时带上这几样，能省掉一轮来回：Hugo 版本（hugo version 完整输出）、主题版本（hugo mod graph | grep oink）、第一条完整错误、能复现的最小页面或最小站点。

• 主题与文档的问题：https://github.com/pgsty/oink/issues
• 本站内容的问题：https://github.com/pgsty/oink.pgsty.com/issues
• 上游 Docsy 的兼容性讨论：https://github.com/google/docsy/discussions

相关

• 本地预览 — 干净构建、清缓存、容器与工作区
• 发布上线 — baseURL、验收清单与回滚
• 版本升级 — 升级引入的问题与迁移工具
• 全文检索 — 索引范围、权重与 Algolia
• 多语言 — 语言配置与锚点对齐流程