Standard File and Directory Set

层次结构和保留名称

文件和目录集，保留的文件和目录名称，以及从内容源根目录开始的层次结构，统称为Antora的标准文件和目录集，帮助Antora确定要收集哪些文件，每个文件的作用，如何对每个文件进行分类以及要忽略哪些文件。示例1显示了Antora期望的层次结构，如果使用了构成标准文件和目录集的所有必需和可选文件和目录。

在以下示例中，📒 repository代表单个引用的文件树的根，例如git存储库中的一个分支。

示例1. 位于存储库根目录的标准文件和目录集的所有必需和可选文件和目录

📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📁 attachments (5)
      📁 examples (6)
      📁 images (7)
      📁 pages (8)
      📁 partials (9)
      📄 nav.adoc (10)
    📂 named-module (11)
      📁 pages
      📄 nav.adoc (12)
  📁 packages (13)

1	存储库根目录和内容源根目录。默认情况下，Antora假定内容源根目录位于存储库的根目录，除非在站点的playbook中为内容源分配了`start_path`或`start_paths`键的值。
2	每个内容源根目录都需要一个组件版本描述符文件，命名为antora.yml（保留文件名）。antora.yml文件告诉Antora应收集和处理名为modules的目录中的内容。
3	必需的名为modules的目录（保留目录名）。modules目录必须与内容源根目录中的antora.yml文件处于相同的层次级别。也就是说，antora.yml文件和modules目录是兄弟目录。一个modules目录必须至少包含一个一个ROOT模块目录或一个命名模块目录。
4	可选的ROOT模块目录。Antora对ROOT模块目录中的可发布资源应用特殊行为。ROOT是一个保留的目录名称，必须使用大写字母。一个模块目录必须至少包含一个家族目录。
5	可选的attachments家族目录（保留目录名）。
6	可选的examples家族目录（保留目录名）。
7	可选的images家族目录（保留目录名）。
8	可选的pages家族目录（保留目录名）。
9	可选的partials家族目录（保留目录名）。
10	可选的导航文件，命名为nav.adoc。
11	可选的命名模块目录。您可以根据需要创建多个命名模块目录。一个模块目录必须至少包含一个家族目录。
12	可选的导航文件，命名为nav.adoc。
13	Antora不会处理此目录中的文件，因为它位于modules目录之外。

在示例1中，内容源根目录位于存储库的根目录。但是，内容源根目录不一定要位于存储库的根目录。在示例2中，内容源根目录位于存储库的一个目录中。

示例2. 位于存储库目录中的标准文件和目录集的所有必需和可选文件和目录

📒 repository (1)
  📁 config (2)
  📂 docs (3)
    📄 antora.yml
    📂 modules
      📂 ROOT
        📁 attachments
        📁 examples
        📁 images
        📁 pages
        📁 partials
        📄 nav.adoc
      📂 named-module
        📁 pages
    📁 notes (4)
  📄 README.adoc (5)

1	存储库根目录
2	Antora会忽略此目录，因为它没有在站点的playbook中指定为内容源根目录（本示例目的）。
3	根据站点的playbook使用`start_path`或`start_paths`键指定的内容源根目录（本示例目的）。
4	Antora不会处理此目录中的文件，因为它位于modules目录之外。
5	Antora会忽略此文件，因为它不在内容源根目录中。

默认情况下，Antora假定存储库根目录和内容源根目录是相同的。如果您构建了一个内容源根目录位于存储库目录中的存储库结构，您必须在站点的playbook中使用start_path或start_paths键指定目录的路径。

在下一节中，您可以看到满足Antora的有效标准文件和目录集的最低要求的两个内容源示例。

最低要求

从内容源根目录，Antora必须找到：

位于内容源根目录的antora.yml文件
与antora.yml文件在同一层次的modules目录
modules目录中至少有一个模块目录
至少有一个包含至少一个源文件的家族目录在模块目录中

让我们看两个示例，展示符合最低要求的标准文件和目录集。在示例 3中的目录和文件集是有效的，因为它包含了所需的antora.yml和modules目录在内容源根目录。 modules目录包含一个模块目录，在这种情况下是特殊的ROOT模块目录。进而，ROOT模块目录包含一个包含一个源文件的家族目录。

示例 3. 包含ROOT模块目录的有效标准文件和目录集

📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📂 pages (5)
        📄 page-source-file.adoc (6)

1	在这个示例中，内容源根目录位于存储库的根目录。
2	组件版本描述符文件，有效的文件名为antora.yml。
3	modules目录。
4	ROOT模块目录。
5	pages家族目录。
6	一个页面的源文件。

在示例 4中，内容源根目录位于目录ops-training。

示例 4. 包含命名模块目录的有效标准文件和目录集

📒 repository
  📂 courses
    📂 ops-training (1)
      📄 antora.yml (2)
      📂 modules (3)
        📂 rz-interface (4)
          📂 images (5)
            📄 image-source-file.ext (6)

1	内容源根目录。
2	组件版本描述符文件，有效的文件名为antora.yml。
3	modules目录。
4	一个名为rz-interface的模块目录。
5	images家族目录。
6	一个图片的源文件。

示例 4中的标准目录和文件集也是有效的。

隐藏和未发布文件

隐藏文件是指存储在Antora标准目录层次结构中以点（.）开头的任何文件。没有文件扩展名的文件也是隐藏的，除非它们存储在examples目录或partials目录中。隐藏文件不会添加到Antora的内容目录中，因此不会被分配资源ID，无法被引用，也不会被发布。

示例 5. 包含隐藏文件的标准目录集

📒 repository
  📄 antora.yml
  📂 modules
    📂 ROOT
      📂 examples
        📄 .hidden-example-file.ext (1)
        📄 example-file (2)
      📂 pages
        📄 .hidden-page-file.adoc (3)
        📄 hidden-page-file (4)

1	Antora不会将这个示例文件加载到内容目录中，因为它的文件名以点（`.`）开头。
2	存储在examples目录中的文件不需要具有文件扩展名，因此Antora将这个示例文件加载到内容目录中。
3	Antora不会将这个页面文件加载到内容目录中或发布它，因为它的文件名以点（`.`）开头。
4	Antora不会将这个页面文件加载到内容目录中或发布它，因为它缺少文件扩展名，而页面文件必须具有文件扩展名。

除非对于某种文件类型来说没有文件扩展名是典型的，比如Dockerfile，最好的做法是使用有效的文件扩展名保存部分和示例源文件。如果不使用文件扩展名保存部分和示例文件，您可能无法使用将额外行为应用于部分或示例文件的Antora或Asciidoctor扩展。

未发布文件是指存储在Antora标准目录层次结构中以下划线（_）开头的任何文件。未发布文件将被添加到内容目录中，分配资源ID（如果适用），并可以被引用。但是，未发布文件不会自动发布，即使它存储在可发布家族的文件夹中（即pages、images或attachments）。

示例 6. 包含未发布文件的标准目录集

📒 repository
  📄 antora.yml
  📂 modules
    📂 ROOT
      📂 images
        📄 _unpublished-image-file.ext (1)
      📂 pages
        📄 _unpublished-page-file.adoc (2)

1	以下划线（`_`）开头的图像文件将被加载到内容目录中，并可以被图像宏引用。但是，即使它存储在可发布家族的文件夹中，该图像也不会自动发布。
2	以下划线（`_`）开头的页面文件将被加载到内容目录中，并可以被包含指令引用。但是，即使它存储在可发布家族的文件夹中，该页面也不会作为自己的页面发布，因此无法通过xref宏引用。