包含部分内容
部分的AsciiDoc包含指令
AsciiDoc包含指令将部分源文件中的内容插入到另一个部分或页面中。包含指令接受部分、示例和页面的Antora资源ID作为值。
尽管部分通常是AsciiDoc片段，但部分可以是没有文件扩展名限制的任何文本文档。如果部分不是AsciiDoc，则必须确保将其插入到接受非AsciiDoc内容的AsciiDoc文档中，例如图表块、代码块或CSV表格。如果部分是代码示例，则建议将其存储为示例而不是部分，因为示例是部分的一种专门形式。本页重点介绍AsciiDoc文件的部分。
示例1展示了具有部分的完全限定资源ID的包含指令的结构。因为包含指令用于引用其他资源，所以在将其分配给包含指令时，必须在部分的资源ID中指定partial$系列坐标。
include::version@component:module:partial$file-coordinate-of-target-partial.adoc[可选属性]包含指令至少由指令前缀（include::）、目标部分的资源ID和一组方括号（[]）组成。您可以在方括号内指定可选属性，作为由逗号分隔的键值对。 目标部分是当前页面引用的部分的源文件。通过将其资源ID分配给当前页面中的包含指令，引用目标部分。 当前页面是包含指令所在的页面源文件。
当Antora运行时，从目标部分插入到当前页面的内容将插入到输入包含指令的位置。目标部分的内容在插入到当前页面后进行转换。这意味着当前页面的组件版本、模块、属性和其他元素将应用于或可能影响从目标部分包含的内容。请参阅当前页面上下文和结构以了解更多信息。
将一个局部文件插入到页面中
-
在您的IDE或纯文本编辑器中打开要插入部分的页面。在这一步和随后的步骤中，让我们假设您已经打开了文件ranges.adoc。
示例2. ranges.adoc（当前页面）= 徒步穿越山脉 == 地形 树线以上，小径变得艰难。当前页面ranges.adoc属于组件版本colorado 5.2和模块ROOT，如示例3所示。
示例3. 分配给colorado 5.2的目录和文件📄 antora.yml (1) 📂 modules 📂 ROOT (2) 📂 pages (3) 📄 index.adoc 📄 ranges.adoc 📂 partials (4) 📄 treeline-warning.adoc1 将组件版本定义为colorado 5.2 2 定义ROOT模块 3 将后续文件定义为页面 4 将后续文件定义为部分 -
在当前页面中，选择要插入部分内容的行。在行的开头，输入指令名称后跟两个冒号
include::。示例4. ranges.adoc（当前页面）树线以上，小径变得艰难。 include::
-
让我们引用目标部分treeline-warning.adoc，并将目标部分的资源ID分配给包含指令。因为treeline-warning.adoc和ranges.adoc属于相同的组件版本和模块（参见示例3），所以只需要指定目标部分的
partial$家族坐标和文件坐标。示例5. ranges.adoc（当前页面）树线以上，小径变得艰难。 include::partial$treeline-warning.adoc
treeline-warning.adoc部分的文件坐标是
treeline-warning.adoc。目标部分的文件坐标仅包括其文件名和文件扩展名，因为treeline-warning.adoc存储在partials目录的根目录中。默认情况下，当未指定坐标时，包含指令会假定家族坐标为 page$。如果忘记使用partial$坐标，Antora将报告错误，因为它将无法找到部分。 -
在目标部分的资源ID之后，用一组方括号
[]完成指令。示例6. ranges.adoc（当前页面）树线以上，小径变得艰难。 include::partial$treeline-warning.adoc[]
包含指令的方括号可以包含一组可选属性，例如
lines、tag或tags。属性以逗号分隔的键值对形式输入。有关lines、tag和tags语法的详细信息，请参阅AsciiDoc包含指令文档。
就是这样！您已经创建了一个包含指令，将目标部分插入到当前页面中。
上述说明向您展示了如何在最常见的情况下将部分插入到页面中——目标部分和当前页面属于相同的组件版本和模块，并且目标部分存储在partials文件夹的根目录中。但是，如果目标部分存储在partials目录的子目录中，则其文件坐标必须指定partials相对目录路径以及文件名和文件扩展名。
include::partial$target-partial-filename.adoc[] (1)
include::partial$path/to/target-partial-filename.adoc[] (2)
include::partial$./target-partial-filename.adoc[] (3)| 1 | 当目标部分存储在partials目录的根目录中时，目标部分的文件坐标。 |
| 2 | 当目标部分存储在partials目录的子目录中时，目标部分的文件坐标。 |
| 3 | 当目标部分和当前页面存储在具有平行家族相对目录路径的子目录中时，目标部分的文件坐标。这是一个高级用例。 |
文件与局部相对目录路径配合
当目标局部存储在partials目录的子目录中时，在其文件坐标中需要包含partials相对目录路径。
include::partial$path/to/target-partial-filename.adoc[可选属性]让我们使用属于组件版本的文件作为本节示例的基础，参见示例9。
📄 antora.yml (1)
📂 modules
📂 la-garita (2)
📂 pages (3)
📄 ridge.adoc
📂 partials (4)
📂 climate (5)
📄 gear-list.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义名为la-garita的模块 |
| 3 | 将后续文件定义为页面 |
| 4 | 将后续文件定义为局部 |
| 5 | partials中包含局部源文件的子目录 |
让我们从ridge.adoc引用gear-list.adoc。如上述示例9所示，局部和页面属于la-garita模块。在示例10中，当前页面ridge.adoc中的包含指令引用了目标局部gear-list.adoc。
== 计划您的徒步旅行
include::partial$climate/gear-list.adoc[]如示例10所示，家族坐标为partial$，gear-list.adoc的文件坐标为climate/gear-list.adoc。 gear-list.adoc的文件坐标包括其partials相对目录路径、文件名和文件扩展名，因为它存储在子目录climate中。
在特殊情况下，目标局部的partials相对目录路径和当前页面的pages相对目录路径平行时，可以用相对路径标记./替换partials相对目录路径。 |
包含另一个模块中的部分内容
include::module:partial$target-partial-filename.adoc[可选属性] (1)
include::module:partial$path/to/target-partial-filename.adoc[可选属性] (2)| 1 | 当目标部分和当前页面属于同一组件版本但不属于同一模块时，在包含指令中将目标部分的模块、partial$和文件坐标分配给包含指令。当目标部分存储在partials系列目录的根目录时，目标部分的文件坐标是其文件名和文件扩展名。 |
| 2 | 如果目标部分存储在partials目录的子目录中，则目标部分的文件坐标必须指定其partials相对目录路径、文件名和文件扩展名。 |
让我们使用在示例 12中显示的组件版本中的文件作为本节示例的基础。
📄 antora.yml (1)
📂 modules
📂 la-garita (2)
📂 pages (3)
📄 ridge.adoc
📂 ROOT (4)
📂 partials (5)
📄 treeline-warning.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义一个名为la-garita的模块 |
| 3 | 将后续文件定义为页面 |
| 4 | 定义一个名为ROOT的模块 |
| 5 | 将后续文件定义为部分内容 |
让我们将treeline-warning.adoc部分插入到ridge.adoc页面中。这意味着源文件treeline-warning.adoc是目标部分，ridge.adoc是当前页面。如上所示的示例 12，ridge.adoc页面属于la-garita模块，treeline-warning.adoc部分属于ROOT模块。
示例 13显示了在ridge.adoc中引用部分treeline-warning.adoc的包含指令。目标部分的模块、partial$和文件坐标被分配给包含指令。
include::ROOT:partial$treeline-warning.adoc[]如示例 13所示，目标部分的模块坐标是ROOT，其系列坐标是partial$，文件坐标是treeline-warning.adoc。
从另一个组件包含部分内容
当目标部分和当前页面不属于同一文档组件时，在分配给包含指令的资源ID中指定部分的版本、组件、模块、系列和文件坐标。
include::version@component:module:partial$target-partial-filename.adoc[] (1)
include::version@component:module:partial$path/to/target-partial-filename.adoc[] (2)
include::component:module:partial$file-coordinate-of-target-partial.adoc[] (3)| 1 | 当目标部分和当前页面不属于同一组件版本时，将目标部分的版本、组件、模块、系列和文件坐标分配给包含指令。当目标部分位于存储在partials系列目录的根目录时，目标部分的文件坐标是其文件名和文件扩展名。 |
| 2 | 如果目标部分存储在partials目录的子目录中，则目标部分的文件坐标必须指定其partials相对目录路径、文件名和文件扩展名。 |
| 3 | 如果未指定版本坐标，Antora将在运行时使用目标部分组件的最新版本来完成资源ID。此行为仅适用于目标部分和当前页面属于不同文档组件的情况。 |
📄 antora.yml (1)
📂 modules
📂 ROOT (2)
📂 pages (3)
📄 index.adoc
📂 partials (4)
📄 treeline-warning.adoc
| 1 | 将组件版本定义为colorado 5.2 |
| 2 | 定义ROOT模块 |
| 3 | 将后续源文件定义为页面 |
| 4 | 将后续源文件定义为部分 |
📄 antora.yml (1)
📂 modules
📂 sierra-madre (2)
📂 pages (3)
📄 elevation.adoc
| 1 | 将组件版本定义为wyoming 1.0 |
| 2 | 定义名为sierra-madre的模块 |
| 3 | 将后续文件定义为页面 |
使用来自示例 15和示例 16的文件，让我们从elevation.adoc（当前页面）中引用treeline-warning.adoc（目标部分）。treeline-warning.adoc部分属于组件版本colorado 5.2。elevation.adoc页面属于组件版本wyoming 1.0。
示例 17中的包含指令将treeline-warning.adoc部分的内容嵌入到elevation.adoc页面中。
include::5.2@colorado:ROOT:partial$treeline-warning.adoc[]如示例 17所示，目标部分的版本坐标为5.2，组件坐标为colorado，模块坐标为ROOT，系列坐标为partial$，文件坐标为treeline-warning.adoc。您还可以将treeline-warning.adoc的资源ID指定为5.2@colorado::partial$treeline-warning.adoc（注意模块坐标ROOT似乎缺失）。当指定目标部分的组件坐标，并且目标部分属于ROOT模块时，模块坐标ROOT不必显式指定。但是，您仍然必须输入接下来会跟随模块坐标的冒号（:）。这种简写仅在指定组件坐标且目标部分的模块坐标为ROOT时有效。
使用部分的最新版本
| 此行为仅适用于目标部分和当前页面属于不同文档组件的情况！ |
如果在分配给包含指令的资源ID中未指定版本，且目标部分和当前页面不属于同一组件，Antora将在运行时使用目标部分组件的最新版本的版本坐标来完成资源ID。
📄 antora.yml (1)
📂 modules
📂 la-garita
📂 pages
📄 willow-creek.adoc
| 1 | 将组件版本定义为 colorado 5.2 |
📄 antora.yml (1)
📂 modules
📂 sierra-madre
📂 pages
📄 elevation.adoc
📂 partials
📄 bears.adoc
| 1 | 将组件版本定义为 wyoming 1.0 |
📄 antora.yml (1)
📂 modules
📂 sierra-madre
📂 pages
📄 elevation.adoc
📂 partials
📄 bears.adoc
| 1 | 将组件版本定义为 wyoming 1.5 |
让我们从当前页面 willow-creek.adoc（当前页面）引用目标部分 bears.adoc。 willow-creek.adoc 属于组件版本 colorado 5.2。有两个名为 bears.adoc 的文件属于 wyoming 组件，sierra-madre 模块和 partials 系列。一个 bears.adoc 属于版本 1.0，另一个 bears.adoc 属于版本 1.5。
示例21 显示了一个包含指令，引用了 bears.adoc（目标部分）从 willow-creek.adoc（当前页面）。请注意，未指定目标部分的版本坐标。
include::wyoming:sierra-madre:partial$bears.adoc[]当 Antora 运行时，它将根据其版本排序规则和最新版本标准，将 wyoming 1.5 识别为 wyoming 组件的最新版本。因为在示例21中未指定版本坐标，Antora 将使用最新 wyoming 组件的版本坐标 — 1.5 — 来完成分配给包含指令的资源ID。
| 仅当未指定版本坐标且目标部分和当前页面属于不同组件时，才适用链接到最新版本的此行为。如果在资源ID中未指定版本和组件坐标，则 Antora 假定目标部分属于与当前页面相同的组件版本，并使用当前页面的版本和组件坐标来完成目标部分的资源ID。 |
包含指令的放置
包含指令放置在新行的开头。当您在包含指令上方和下方输入空行时，来自目标部分的内容将显示为独立块。您可以通过将包含指令直接放置在当前页面的内容旁边的新行上，将目标部分的内容附加到当前页面的块中。
页面中的一个段落。
include::partial$cli-options.adoc[tag=compass] (1)
一行内容。
include::partial$addendum.adoc[] (2)
另一行内容。| 1 | 要将包含的内容显示为独立块，请确保包含指令上方和下方有空行。 |
| 2 | 要将包含的内容附加到当前页面的块中，请在当前页面的内容行的上方、中间或下方直接输入包含指令。 |
包含图表源
如果您在页面中使用从源生成的图表，您可能希望将图表的源存储在单独的文件中。您可以选择将该源存储为示例或部分。由于源不是代码示例，部分似乎是更合乎逻辑的地方。
在部分目录下创建一个名为diagrams的文件夹。然后，将您的图表源存储在该文件夹中。假设文件名为 partials/diagrams/my-schema.puml。现在，您可以将该源包含到您的页面中，如下所示：
[plantuml,my-schema,svg]
....
include::partial$diagrams/my-schema.puml[]
....您可以像处理其他部分一样，引用其他模块、版本或组件中的图表源。