包含页面
使用AsciiDoc包含指令和页面的资源ID，可以将页面或页面的部分插入到站点中的任何其他页面中。
页面的AsciiDoc包含指令
AsciiDoc包含指令将页面的源文件中的内容插入到另一个页面中。包含指令接受部分、示例和页面的Antora资源ID作为值。
示例1展示了带有页面的完全限定资源ID的包含指令的结构。默认情况下，当未指定家族坐标时，包含指令会假定家族坐标为page$。
include::version@component:module:file-coordinate-of-target-page.adoc[可选属性]包含指令由指令前缀（include::）、目标页面的资源ID和一组方括号（[]）组成。您可以在方括号内指定可选属性，作为由逗号分隔的键值对。 目标页面是当前页面引用的页面的源文件。通过将其资源ID分配给当前页面中的包含指令，引用目标页面。 当前页面是包含指令所在的页面源文件。
当Antora运行时，从目标页面插入到当前页面的源内容会在包含指令输入的位置处插入。插入到当前页面后，目标页面的内容会被转换。这意味着当前页面的组件版本、模块、属性和其他元素会应用于或可能影响从目标页面包含的内容。查看当前页面上下文和结构以了解更多信息。
将页面插入到页面中
-
在您的IDE或纯文本编辑器中，打开您想要从目标页面包含内容的页面。在这一步和随后的步骤中，让我们假设您已经打开了文件ranges.adoc。
示例 2. ranges.adoc（当前页面）Sawatch Range中有三个山口。当前页面ranges.adoc属于组件版本colorado 5.2和模块ROOT，如示例 3所示。
示例 3. 分配给colorado 5.2的目录和文件📄 antora.yml (1) 📂 modules 📂 ROOT (2) 📂 pages (3) 📄 cottonwood-pass.adoc 📄 index.adoc 📄 ranges.adoc1 将组件版本定义为colorado 5.2 2 定义ROOT模块 3 将后续文件定义为页面 -
在当前页面中，选择要插入页面内容的行。在该行的开头，输入指令名称，后跟两个冒号，
include::。示例 4. ranges.adoc（当前页面）在Sawatch Range中有三个山口。 include::
-
让我们引用目标页面cottonwood-pass.adoc。将目标页面的资源ID分配给包含指令。因为cottonwood-pass.adoc和ranges.adoc属于相同的组件版本和模块（请参见示例 3），因此只需要指定目标页面的文件坐标。
示例 5. ranges.adoc（当前页面）在Sawatch Range中有三个山口。 include::cottonwood-pass.adoc
cottonwood-pass.adoc页面的文件坐标是
cottonwood-pass.adoc。目标页面的文件坐标仅包括其文件名和文件扩展名，因为cottonwood-pass.adoc存储在pages目录的根目录中。如果愿意，您可以在资源ID中指定 page$系列坐标，但在将页面包含到页面中时，这并非必需。当未指定时，包含指令会假定系列坐标为page$。 -
在目标页面的资源ID之后，用一对方括号（
[]）完成指令。示例 6. ranges.adoc（当前页面）在Sawatch Range中有三个山口。 include::cottonwood-pass.adoc[]
包含指令的方括号中可以包含一组可选属性，例如
lines、tag或tags。这些属性以逗号分隔的键值对形式输入。有关lines、tag和tags语法的详细信息，请参阅AsciiDoc包含指令文档。
就是这样！您已经创建了一个包含指令，将目标页面插入到当前页面中。
目标页面的文件坐标结构取决于目标页面是存储在pages家族目录的根目录中（如前述说明）还是存储在pages目录的子目录中。
include::target-page-filename.adoc[] (1)
include::path/to/target-page-filename.adoc[] (2)
include::./target-page-filename.adoc[] (3)| 1 | 当目标页面存储在pages目录的根目录中时，目标页面的文件坐标。 |
| 2 | 当目标页面存储在pages目录的子目录中时，目标页面的文件坐标。 |
| 3 | 当目标页面和当前页面存储在pages目录的相同子目录中时，目标页面的文件坐标。 |
带有pages-relative目录路径的文件坐标
当目标页面存储在pages目录的子目录中时，目标页面的pages-relative目录路径在其文件坐标中是必需的。
include::path/to/target-page-filename.adoc[可选属性]让我们以示例 9中属于组件版本的文件为基础，来说明本节中的示例。
📄 antora.yml (1)
📂 modules
📂 ROOT (2)
📂 pages (3)
📄 cottonwood-pass.adoc
📄 index.adoc
📄 ranges.adoc
📂 supplies (4)
📄 gear.adoc
📄 safety.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义ROOT模块 |
| 3 | 将后续文件定义为页面 |
| 4 | pages中包含页面源文件的子目录 |
让我们从cottonwood-pass.adoc引用safety.adoc。如上述示例 9所示，目标页面和当前页面属于ROOT模块。在示例 10中，cottonwood-pass.adoc页面（当前页面）中的包含指令引用safety.adoc文件（目标页面）。
== 旅行计划
include::supplies/safety.adoc[]如示例 10所示，safety.adoc的文件坐标是supplies/safety.adoc.adoc。safety.adoc的文件坐标包括其pages-relative目录路径、文件名和文件扩展名，因为它存储在supplies子目录中，而当前页面cottonwood-pass.adoc存储在pages目录中。如果当前页面和目标页面存储在同一子目录中，您可以使用相对路径标记./代替pages-relative目录路径。
使用相对路径标记的文件坐标
include::./target-page-filename.adoc[]让我们以在本节示例中展示的组件版本所属的页面为基础，示例12。
📄 antora.yml (1)
📂 modules
📂 ROOT (2)
📂 pages (3)
📄 cottonwood-pass.adoc
📄 index.adoc
📄 ranges.adoc
📂 supplies (4)
📄 gear.adoc
📄 safety.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义ROOT模块 |
| 3 | 将后续文件定义为页面 |
| 4 | pages中包含页面源文件的子目录 |
让我们从safety.adoc引用gear.adoc。示例12显示这两个文件都存储在pages目录的supplies子目录中，并且这两个文件都属于同一组件版本的ROOT模块。当目标页面和当前页面存储在pages目录的同一子目录中时，可以使用相对路径标记./来缩写目标页面的文件坐标。
在示例13中，safety.adoc页面（当前页面）中的包含指令引用了gear.adoc页面（目标页面）。
include::./gear.adoc[]如示例13所示，当从safety.adoc引用gear.adoc时，文件坐标为./gear.adoc。由于两个页面都存储在supplies子目录中，因此目标页面的文件坐标的pages-相对目录路径被替换为./标记。
当文件坐标中未使用./标记时，包含指令可能会解析目标页面。但是，我们强烈建议在引用与当前页面存储在同一子目录中的目标页面时使用./标记。 |
嵌入另一个模块或组件版本的页面
您可以通过将目标页面的模块坐标或版本、组件和模块坐标分配给包含指令，将任何模块或组件版本的页面包含到属于您站点的另一个页面中。
include::module:file-coordinate-of-target-page.adoc[] (1)
include::version@component:module:file-coordinate-of-target-page.adoc[] (2)
include::component:module:file-coordinate-of-target-page.adoc[] (3)| 1 | 当目标页面和当前页面属于同一组件版本但不属于同一模块时，将目标页面的模块和文件坐标分配给包含指令。 |
| 2 | 当目标页面和当前页面不属于同一组件版本时，将目标页面的版本、组件、模块和文件坐标分配给包含指令。 |
| 3 | 如果未指定版本坐标，Antora将在运行时使用目标页面组件的最新版本来完成资源ID。此行为仅适用于目标页面和当前页面属于不同文档组件的情况。 |
例如，要将cottonwood-pass.adoc（目标页面）的内容嵌入到属于colorado 5.2组件版本的不同模块的页面（当前页面）中，请在包含指令中指定目标页面的模块坐标。
include::ROOT:cottonwood-pass.adoc[]如果当前页面属于与cottonwood-pass.adoc（目标页面）不同的组件版本，请指定目标页面的版本、组件、模块和文件坐标。
include::5.2@colorado:ROOT:cottonwood-pass.adoc[]如示例 16 所示，目标页面的版本坐标为 5.2，其组件坐标为 colorado，其模块坐标为 ROOT，文件坐标为 cottonwood-pass.adoc。
包含指令的放置
包含指令放置在新行的开头。当在包含指令上方和下方输入空行时，来自目标页面的内容将显示为独立块。您可以通过将包含指令直接放置在当前页面的内容旁边的新行上，将目标页面的内容附加到当前页面的块中。
页面中的一个段落。
include::resource-id-of-target-page.adoc[tag=value] (1)
一行内容。
include::resource-id-of-target-page.adoc[] (2)
另一行内容。| 1 | 要将包含的内容显示为独立块，请确保在包含指令之前和之后有空行。 |
| 2 | 要将包含的内容附加到当前页面的块中，请在当前页面的内容行的上方、中间或下方直接输入包含指令。 |