如何组织您的内容文件
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引用。
文件位置和URL
源文件的位置不决定发布文件的位置。一旦源文件加载到Antora的VFS中，将操作文件的元数据，包括计算文件的输出位置和URL。每个文件家族对这些值的计算方式不同。源文件的位置、发布文件在站点中的放置位置或访问该文件的方式之间的关联并非硬编码。
查看什么是组件版本？和什么是antora.yml？以了解如何为内容源文件组分配组件名称、版本和其他可选信息。
git引用名称
git引用名称，包括分支和标签的名称，应仅包含无需进行URL编码的字符。这一规则不受git强制执行，但违反它可能会在Antora中引起微妙的问题。
虽然引用名称不会出现在已发布资源的URL中，但它用于指回文件的来源。具体来说，使用需要进行URL编码的字符在编辑页面的URL组装中会导致问题。
例如，字符#违反了这一规则，必须编码为%23。尽管Antora可以愉快地构建包含此字符的编辑URL，但URL不会被浏览器按预期解释。这是因为#标记了发送到服务器的URL和仅由浏览器看到的片段之间的边界。结果将是不完整的URL，因此是404页面。
在引用名称中使用通用目录分隔符/是可以接受的。通过这样做，它有效地将引用组织成文件夹结构（例如r/3.0.x）。但是，这种策略可能会影响引用名称匹配。在引用名称模式中，字符*不匹配/（它不跨越文件夹的边界）。因此，要匹配诸如r/3.0.x的引用名称，必须使用模式r/*而不是r*。