最佳实践

• 1: Hugo 内容技巧
• 2: 组织内容

1 - Hugo 内容技巧

Docsy 是一款面向 Hugo 静态站点生成器的主题。如果你还不熟悉 Hugo，本页汇总了一些添加和编辑站点内容时的实用技巧及常见陷阱。也欢迎补充自己的经验！

链接

默认情况下，Hugo 会原样保留链接中的普通相对 URL（它们在站点生成的 HTML 中仍是相对链接）。因此，像 [相对交叉链接](../../peer-folder/sub-file.md) 这样硬编码的相对链接，其行为可能与你在本地文件系统中看到的不同。为了避免生成的站点出现断链，可以使用 Hugo 内置的链接短代码，例如 relref。例如，Hugo 中的 {{< ref "filename.md" >}} 会真正找到名为 filename.md 的文件，并自动生成指向它的链接。

但请注意，ref 和 relref 链接不适用于 _index 或 index 文件（例如本站的内容首页）。指向分区首页或其他索引页时，需要使用普通 Markdown 链接，并从站点根 URL 开始写路径，例如：/docs/content/。

进一步了解链接的用法。

2 - 组织内容

查看我们的示例站点，你会发现其中的“文档”分区被划分为多个子分区；每个子分区都附有建议，说明适合放入哪些内容。

必须采用这种结构吗？

当然不必！示例站点的结构面向功能众多、潜在任务复杂、参考资料丰富的大型产品和大型文档集。对于更简单的文档集（比如本站），围绕用户需要了解的具体功能来组织文档就很好。即使面对大型文档集，你也可能发现这套结构不能直接照搬，或者没有必要用到其中的全部分区类型。

不过，我们建议至少提供以下内容（本站也是如此）：

• 产品的 概览——可以放在文档首页，也可以单独成页，用来告诉用户为什么值得关注你的项目；
• 开始使用 页面；
• 一些 示例。

你也可以围绕项目功能编写任务指南或操作方法。如果更喜欢本站这种精简结构，可以复制整个 Docsy 用户指南站点，也可以只复制其中的文档分区。

进一步了解 Hugo 和 Docsy 如何利用文件夹及其他文件组织站点。

为什么采用这种结构？

示例站点的结构来自我们为不同类型项目创建和使用大型文档集的经验，也参考了针对一些大型站点开展的用户研究。研究表明，用户最关心并会立即寻找的是“开始”或“开始使用”分区——顾名思义，他们希望马上动手；其次是可供探索和复制的示例。因此，我们把这两类内容设计成站点中醒目的顶层文档分区。

用户还希望找到易于检索的“配方”，以便完成具体任务，并把这些配方组合成自己的应用或项目。因此，我们建议把这类内容组织为“任务”。概念说明、参考文档和端到端教程等其他内容类型并非对所有文档集都同样重要，对小型项目尤其如此。示例站点也明确说明这些分区均为可选项。

随着我们进一步了解用户如何使用技术文档，尤其是开源项目文档，我们还会继续完善示例站点的结构。

写作风格指南

本指南和示例站点只介绍如何把文档内容组织成页面和分区。至于每个页面应如何组织和撰写内容，我们推荐参考 Google 开发者文档风格指南，尤其是其中的风格指南要点。