标准文件和目录集

Antora 根据内容源根目录中找到的一组分层文件和目录来收集和处理内容源文件。本页将介绍该层次结构、它使用的保留目录和文件名，以及收集或忽略哪些文件的规则。

层次结构和保留名称

从内容源根开始的文件和目录集、保留的文件和目录名称以及它们的层次结构(统称为 Antora 的标准文件和目录集)有助于 Antora 确定要收集哪些文件、每个文件的角色、如何对每个文件进行分类以及要忽略哪些文件。https://docs.antora.org/antora/latest/standard-directories/#ex-standard-dirs-root[示例1] 显示了使用构成标准文件和目录集的所有必需的和可选的文件和目录(Antora 期望的层次结构)。

NOTE: 在下面的示例中，repository 表示 git 存储库中单个引用(如分支)的文件树的根。

Example 1. Example 1. All required and optional files and directories of a standard file and directory set located at a repository root

📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📁 attachments (5)
      📁 examples (6)
      📁 images (7)
      📁 pagesAlian (8)
      📁 partials (9)
      📄 nav.adoc (10)
    📂 named-module (11)
      📁 pagesAlian
      📄 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 文件和模块目录是兄弟关系。模块目录必须至少包含一个 ROOT 模块目录或一个命名模块目录。
4	可选的 ROOT模块目录。Antora 对 ROOT 模块目录中的可发布资源应用特殊行为。ROOT 为保留目录名，必须全大写。模块目录必须至少包含一个族(family)目录。
5	可选附件族目录 (保留的目录名)。
6	可选示例族目录 (保留的目录名)。
7	可选图像族目录 (保留目录名)。
8	可选页面族目录 (保留目录名)。
9	可选的部分族目录 (保留的目录名)。
10	可选导航文件 nav.adoc 。
11	可选命名模块目录。您可以根据需要创建任意数量的命名模块目录。模块目录必须至少包含一个族目录。
12	可选导航文件 nav.adoc 。
13	Antora 不会处理这个目录中的文件，因为它位于 modules 目录之外。

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

Example 2. Example 2. All required and optional files and directories of a standard file and directory set located in a directory of a repository

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

1	存储库根
2	Antora 忽略这个目录，因为它没有在站点的剧本中指定为内容源根目录(对于本示例而言)。
3	在站点的剧本中使用 `start_path` 或 `start_paths` 键指定的内容源根(对于本示例而言)。
4	Antora 不会处理这个目录中的文件，因为它位于 modules 目录之外。
5	Antora 忽略这个文件，因为它不在内容源根目录中。 TIP 默认情况下，Antora 假定存储库根和内容源根是相同的。如果您已经构建了一个存储库，其中内容源根位于存储库的某个目录中，那么您必须使用站点 playbook 中的 `start_path` 或 `start_paths` 键指定该目录的路径。

例1 和例2 中显示的许多目录都是可选的。您只需要设置一个模块目录，如果需要的话，它可以是一个 ROOT 或命名模块目录。此外，您只需要在模块目录中设置最适合源文件类型和用途的族(family)目录。例如，如果不向存储在模块目录中的页面插入任何图像，则不需要创建图像目录。

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

最低要求

从一个内容源根，Antora 必须找到：

位于内容源根的 Antora.yml 文件
一个模块目录，位于与 Antora.yml 文件相同的层次结构级别
模块目录中至少有一个模块目录
至少一个族(family)目录，其中模块目录中至少包含一个源文件

让我们看两个示例，它们展示了满足最低要求的标准文件和目录集。例3 中的目录和文件集是有效的，因为它包含所需的 antora.yml 和 modules 目录下的内容源根目录。modules 目录包含一个模块目录，在本例中是特殊的 ROOT 模块目录。反过来，ROOT 模块目录包含一个包含一个源文件的族目录。

Example 3. Example 3. Valid standard file and directory set containing a ROOT module directory

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

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

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

Example 4. Example 4. Valid standard file and directory set containing a named module directory

📒 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	模块目录
4	一个名为 rz-interface 的模块目录
5	图像目录
6	图像的源文件

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

隐藏和未发布的文件

隐藏文件是存储在 Antora 标准目录层次结构中以点( . )开头的任何文件。没有文件扩展名的文件也会被隐藏，除非它们被重新存储在示例目录或部分目录中。隐藏文件不会被添加到 Antora 的内容目录，因此不会被分配资源 ID ，不能被引用，也不会被发布。

Example 5. Example 5. Standard directory set containing hidden files

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

1	Antora 不会将这个示例文件加载到内容目录中，因为它的文件名以点( `.` )开头。
2	存储在 examples 目录中的文件不需要有文件扩展名，因此 Antora 将把这个示例文件加载到内容目录中。
3	Antora 不会将此页面文件加载到内容目录或发布它，因为它的文件名以点( `.` )开头。
4	Antora 不会将此页面文件加载到内容目录中或发布它，因为它缺少文件扩展名，而页面文件必须具有文件扩展名。 IMPORTANT 除非文件类型通常没有文件扩展名(例如 Dockerfile )，否则最好使用有效的文件扩展名保存示例文件和部分源文件。如果您不使用文件扩展名保存部分文件和示例文件，则可能无法使用 Antora 或 Asciidoctor 扩展名来对部分文件或示例文件应用额外的行为。

未发布文件 是存储在 Antora 标准目录层次结构中以下划线( _ )开头的任何文件。未发布的文件被添加到内容目录，分配一个资源ID(如果适用)，并且可以被引用。但是，未发布的文件不会自动发布，即使它存储在可发布族(即页面、图像或附件)的文件夹中也是如此。

Example 6. Example 6. Standard directory set containing unpublished files

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

1	文件名以下划线( `_` )开头的图像文件将加载到内容目录中，并可由图像宏引用。但是，即使图像存储在一个可发布族的文件夹中，它也不会自动发布。
2	文件名以下划线( `_` )开头的页面文件被加载到内容目录中，并可由 include 指令引用。但是，该页不能被 xref 宏引用，因为它不会作为自己的页面发布，即使它存储在一个可发布族的文件夹中。