Oink 根据 Hugo 内容树生成文档侧栏，因此目录结构也是读者体验的一部分，而不只是源码组织细节。先明确读者需要解决的问题，再建立能够快速找到答案的最小层级。

从读者目标出发

为新读者提供一条从产品背景到首次成功操作的短路径；为回访读者提供直达操作指南、参考资料与故障排查的入口。一套实用文档通常需要：

• 说明范围与产品边界的概览；
• 能得到可运行结果的快速上手路径；
• 围绕常见工作的任务指南；
• 参数、API 与兼容性的参考页面；
• 覆盖常见故障的诊断与恢复说明。

当示例能够直接复制或对比时，它们很有价值，但不应取代解释行为的操作步骤与参考资料。

使用可预测的内容类型

每个页面只聚焦一种读者意图：

内容类型	读者的问题
概览	这是什么，什么时候应该使用？
教程	怎样得到第一个可运行结果？
操作指南	怎样完成一项具体任务？
参考	有哪些字段、命令或接口？
解释	系统为什么采用这种行为？
故障排查	怎样诊断故障并恢复？

不要为了复刻组织架构而建立空的一级目录。只有当多篇页面共享稳定的读者目标时，才增加新的分区。

保持浅层结构

优先使用简短明确的 URL，不要建立过深的分类树。通过页面权重安排学习顺序，并让同一分区的权重保持一致间隔，便于插入新页面。每个可导航页面都应提供图标与精简描述，让侧栏和分区索引便于扫描。

Hugo 页面包与分区模型详见添加内容，侧栏行为详见导航与菜单。

同步规划多语言内容

在同一目录中同时创建英文源页面与简体中文译文。页面顺序、读者意图、示例与稳定标题 ID 应保持一致。两种语言的篇幅不必相同，但必须传达等价信息。

检查完整访问路径

移动或新增页面后，检查文档首页、分区索引、侧栏、面包屑、前后页导航、本地搜索与全部首页链接。发布前应构建两种语言，并验证渲染后的片段链接。