如何组织你的内容文件

Antora 使用约定和配置来聚合内容并生成您的站点。在设置或迁移存储库之前，让我们回顾一些可能影响如何组织文档项目和内容文件以使用 Antora 的关键概念。

存储您的内容源文件

Antora 可以通过在分支、标签或本地工作树中的 起始路径 或 多个起始路径 下搜索文件或其 符号链接 ，从众多git存储库中检索内容源文件。Antora 使用的存储库不必专门用于存储文档(因此使用起始路径)。Antora 可以从存储库中检索文件，这些存储库也包含同级层次结构中的应用程序代码、测试和其它材料。Antora 依赖 约定 和 配置 来标识文档内容。

为了从多个和多用途存储库中获取源文件，Antora 要求文档文件是：

虽然不是必需的，但我们强烈建议您始终使用小写的文件名。有些文件系统是区分大小写的，而有些则不是。通过始终使用小写字母，可以避免由于文件系统、web服务器或传输工具没有保留大小写而出现的任何问题。

对内容源文件进行分类

一旦 Antora 从所有 内容源根 收集源文件，它就会通过为每个文件分配元数据来对其进行分类，元数据用于在站点内唯一地标识文件。文件标识符称为资源ID，用于创建来自页面、其它资源和配置的引用。此步骤还隐式地将源文件划分为组件版本。

Antora的虚拟文件系统

Antora 在收集源文件后将它们从存储位置解耦。无论出于何种意图和目的，每个文件的来源都是无关的。换句话说，一旦发现并加载了文件，Antora 就不会返回到文件系统或 git 存储库中读取文件。Antora 的所有文件操作都基于它在收集文件后创建的虚拟文件系统( VFS )。

映射回文件系统上的位置的文件的唯一方面是 家族相对路径 。甚至这种联系也仅仅是为了作者的方便。除了 家族相对路径 之外，文件标识的所有其它部分都基于相关元数据，例如组件名称、版本、模块名称和家族。

文件元数据

那么，文件如何获得这些元数据呢?同一内容源根目录下的所有文件都从名为 antora.yml 的组件版本描述符文件中继承组件名称和版本。这些描述符文件帮助 Antora 将收集到的所有源文件分类并组织到组件版本中。您可以将组件版本视为项目一个版本的所有文档。例如，您现在正在阅读 Antora 3.1 组件版本中的页面。

这些 antora.yml 文件是属于同一个项目版本的内容如何被 Antora 识别的。它也是如何隐式地定义和填充组件版本的。

在内容源根目录中，文件被进一步分组到模块和族文件夹中，这提供了源文件标识的另外两个方面。最后，捕获家族相对路径以唯一地标识家族中的源文件，甚至跨多个存储库或 git 引用。

文件位置和URLs

源文件的位置并不决定发布文件的位置。一旦将源文件加载到 Antora 的 VFS 中，就会对文件的元数据进行操作，其中包括计算文件的输出位置和 URL 。对于如何计算这些值，每个文件族都有不同的规则。找到源文件的位置、发布文件在站点中的位置以及如何访问该文件之间的关联并不是硬性规定的。

参见 什么是组件版本 ? 什么是 antora.yml ?了解如何将组件名称、版本和其它可选信息分配给内容源文件组。