Hugo 内容技巧

Oink 是一款 Hugo 主题，因此普通 Markdown 与 Hugo 内容模型仍是创作基础。遵循以下约定，可以让页面在翻译、重组或部署到子路径后继续保持清晰与稳定。

链接到发布后的路由

面向读者的链接应指向规范发布 URL，而不是相邻源码文件路径。/zh/docs/content/ 这样的根相对链接便于全站审计。如果链接需要在源码移动后继续跟随目标页面，可以使用 Hugo 的 ref 或 relref 短代码：

[配置]({{< ref "/docs/content/configuration" >}})

移动页面后，应为旧公开路径添加 alias，并把所有站内链接更新为新的规范路由。不要让 alias 长期承担站点导航职责。链接与图片行为详见添加内容。

让 front matter 提供有效信息

每个可导航页面都需要清晰的 title、精简的 description、经过安排的 weight 与合适的 Font Awesome icon。描述只用一句话，并确保在普通桌面内容卡片中可以单行显示。只有当导航标签确实需要与页面标题不同时，才添加 linkTitle。

英文是主要源语言；简体中文译文以 .zh.md 形式与其并置。面向读者的元数据必须与正文一样认真翻译。

保持标题 ID 稳定

多语言页面或经常被引用的页面应使用显式标题 ID：

## 故障恢复 {#failure-recovery}

对应中文标题使用同一个 ID。重命名标题时，只要语义没有改变，就应继续保留已经公开的 ID。

把操作流程写成任务

在命令之前说明前提条件，步骤使用祈使句，并给出预期结果或验证命令。区分本地预览、生产构建、托管部署与公开发布证据；前一层成功不能证明后一层已经完成。

检查渲染后的状态

构建两种语言，并在桌面端、移动端、浅色与深色模式下检查代表页面。验证渲染后的标题、片段链接、代码、表格、提示、导航、搜索、打印输出与页面描述。