包括部分

使用 AsciiDoc include 指令和部分资源 ID ，可以将部分插入到站点中的任何页面或其他部分中。

如果您不熟悉 Antora 资源 ID 及其坐标，请参见：

AsciiDoc包含部分指令

一个 AsciiDoc include 指令将部分源文件中的内容插入到另一个部分或页面中。include 指令接受部分、示例和页面的 Antora 资源 ID 作为值。

虽然部分(partial)通常是一个 AsciiDoc 片段，但分部可以是任何文本文档，不受文件扩展名的限制。如果部分不是 AsciiDoc ，则必须确保插入到 AsciiDoc 文档中接受非 AsciiDoc 内容的位置，例如图表块、代码块或 CSV 表。如果部分是代码示例，则建议将其作为示例而不是部分存储，因为示例是部分的特殊形式。本页着重于部分(partials)的 AsciiDoc 文件。

示例1 展示了包含部分的完全限定资源 ID 的 include 指令的结构。因为 include 指令是用来引用其他资源的，所以当它被分配给 include 指令时，partial$ 族坐标必须在分部的资源 ID 中指定。

Example 1. Example 1. Include directive assigned the fully qualified resource ID of a partial

include::version@component:module:partial$file-coordinate-of-target-partial.adoc[optional attribute]

作为最基本的用法，include 指令由指令前缀（ include:: ）、目标部分的资源ID和一组方括号（[]）构成。您可以在方括号中指定可选属性，这些属性由逗号分隔的键值对组成。目标部分是当前页面引用的部分的源文件。在当前页面的内容中，通过将其资源ID分配给 include 指令来引用目标部分。当前页面是包含引用目标部分的 include 指令的页面源文件。

当 Antora 运行时，目标部分的内容会被插入到输入 include 指令的当前页面的位置。插入到当前页面后，目标部分的内容会进行转换。这意味着当前页面的组件版本、模块、属性和其他元素将会被应用到或影响从目标部分包含的内容。请参阅当前页面上下文和结构了解更多信息。

插入部分到一个页面

让我们分解一下将目标部分插入当前页面所需的 AsciiDoc include 指令和资源ID坐标。

在 IDE 或纯文本编辑器中，打开要插入部分的页面。对于这一步和后续步骤，假设您已经打开了 range.adoc 文件。
Example 2. Example 2. ranges.adoc (current page)
= Hike the Ranges == Terrain Above the treeline, the trail becomes a hard scramble.
当前页面，ragnes.adoc 如例3所示，它属于组件版本 colorado 5.2 和模块 ROOT 。
Example 3. Example 3. Directories and files assigned to colorado 5.2
📄 antora.yml (1) 📂 modules 📂 ROOT (2) 📂 pages (3) 📄 index.adoc 📄 ranges.adoc 📂 partials (4) 📄 treeline-warning.adoc
1 将组件版本定义为 Colorado 5.2

2 定义根(ROOT)模块

3 将后续文件定义为页面

4 将后续文件定义为部分文件
在当前页面中，选择希望插入部分内容的行。在该行的开头，输入指令的名称，后面跟着两个冒号，include:: 。
Example 4. Example 4. ranges.adoc (current page)
```
Above the treeline, the trail becomes a hard scramble.

\include::
```
让我们从当前页面引用目标部分，treeline-warning.adoc。将目标分部的资源 ID 分配给 include 指令。treeline-warning.adoc 和 ranges.adoc 属于相同的组件版本和模块(参见例3)。因此，只需要指定 partial$ 族坐标和目标部分的文件坐标。
Example 5. Example 5. ranges.adoc (current page)
Above the treeline, the trail becomes a hard scramble. \include::partial$treeline-warning.adoc
treeline-warning.adoc partial 文件坐标是 treeline-warning.adoc 。由于 treeline-warning 存储在 partials 目录的根目录中，目标部分文件坐标仅由其文件名和文件扩展名组成。

NOTE

默认情况下，当没有指定坐标时，include 指令假定族坐标是 page$ 。如果您忘记使用 partial$ 坐标，那么 Antora 将报告一个错误，因为它将无法找到 partial 。
直接在目标部分(partial)的资源 ID 之后，用一组方括号( [] )完成指令。
Example 6. Example 6. ranges.adoc (current page)
Above the treeline, the trail becomes a hard scramble. include::partial$treeline-warning.adoc[]
include 指令的括号可以包含一个可选的属性列表，比如 lines、tag或tags 。属性以逗号分隔的键值对形式输入。有关行、标记和标记语法的详细信息，请参阅 AsciiDoc include指令文档。

就是这样!您已经创建了一个 include 指令，它将把目标部分(partial)插入当前页面。

前面的说明向您展示了如何在最常见的场景下将部分插入到页面中:目标部分和当前页面属于相同的组件版本和模块，目标部分存储在 partials 文件夹的根目录中。但是，如果目标部分存储在部分目录的子目录中，则其文件坐标除了指定其文件名和文件扩展名外，还必须指定部分相对目录路径。

Example 7. Example 7. current-page.adoc

\include::partial$target-partial-filename.adoc[] (1)

\include::partial$path/to/target-partial-filename.adoc[] (2)

\include::partial$./target-partial-filename.adoc[] (3)

1	目标部分存储在部分目录的根目录时的文件坐标。
2	当目标部分存储在部分目录的子目录中时，它的文件坐标。
3	当目标部分和当前页面存储在具有平行族相对目录路径的子目录中时，目标部分的文件坐标。这是一个高级用例。

此外，当目标部分页面和当前页面不属于相同的模块或组件版本时，您还需要指定额外的资源ID坐标。以下部分提供了展示各种资源ID场景的示例。

使用部分相对目录的文件坐标

当目标部分存储在部分目录的子目录中时，它的文件坐标中需要部分相对目录路径。

Example 8. Example 8. File coordinate when the target partial is stored in a subdirectory of a partials directory

include::partial$path/to/target-partial-filename.adoc[optional attribute]

让我们使用示例9 中属于组件版本的文件作为本节示例的基础。

Example 9. Example 9. Directories and files assigned to colorado 5.2

📄 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` 源文件的 `partials` 中的子目录

让我们从 ridge.adoc 引用 gear-list.adoc 。如您在上面的示例9 中所看到的，这个部分和页面都属于 la-garita 模块。在示例10中，ridge.adoc 页面（当前页面）中的一个 include 指令引用了 gear-list.adoc 文件（目标部分）。

Example 10. Example 10. ridge.adoc (current page)

== Plan your hike

include::partial$climate/gear-list.adoc[]

如示例10所示，族坐标为 partial$ ，gear-list.adoc 的文件坐标为 climate/gear-list.adoc 。 gear-list.adoc 的文件坐标包括它的相对 partials 目录路径、文件名和文件扩展名，因为它存储在子目录 climate 中。

TIP: 在一些特殊情况下，如果目标部分的相对于 partials 目录路径和当前页面的相对于 pages 目录路径相同，则可以将 partials-relative 目录路径替换为相对路径标记 ./ 。

包含另一个模块的一个部分

当目标部分和当前页面不属于同一个模块时，必须在 include 指令中指定目标部分的模块、族和文件坐标。

Example 11. Example 11. Module, family, and file coordinates assigned to an include directive

\include::module:partial$target-partial-filename.adoc[optional attribute] (1)

\include::module:partial$path/to/target-partial-filename.adoc[optional attribute] (2)

1	当目标部分和当前页面属于同一个组件版本但不属于同一个模块时，将目标部分的模块、`partial$` 和文件坐标赋给 `include` 指令。当它存储在 `partials` 族目录的根目录中时，目标 `partial` 文件坐标是它的文件名和文件扩展名。
2	如果目标部分存储在部分目录的子目录中，则目标部分文件坐标必须指定其部分相对目录路径、文件名和文件扩展名。

让我们使用示例12中显示的组件版本的文件作为本节示例的基础。

Example 12. Example 12. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 pagesAlian (3)
      📄 ridge.adoc
  📂 ROOT (4)
    📂 partials (5)
      📄 treeline-warning.adoc

1	将组件版本定义为 Colorado 5.2
2	定义一个名为 La-Garita 的模块
3	将后续文件定义为页面
4	定义一个名为 ROOT 的模块
5	将后续文件定义为部分(partials)文件

让我们将 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 部分的 include 指令。将目标部分的模块、partial$ 和文件坐标分配给 include 指令。

Example 13. Example 13. ridge.adoc (current page)

include::ROOT:partial$treeline-warning.adoc[]

如例13所示，目标 partial 模块坐标是 ROOT ，它的族坐标是 partial$ ，它的文件坐标是 treeline-warning.adoc 。

包含另一个组件的一个部分

当目标部分和当前页面不属于同一文档组件时，请在分配给 include 指令的资源 ID 中指定部分的版本、组件、模块、族和文件坐标。

Example 14. Example 14. Version, component, module, family, and file coordinates assigned to an include directive

\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	当目标部分和当前页面不属于同一组件版本时，将目标部分的版本、组件、模块、族和文件坐标赋给 `include` 指令。当目标局部存储在局部族目录的根目录中时，目标局部文件坐标是它的文件名和文件扩展名。
2	如果目标部分存储在部分目录的子目录中，则目标部分文件坐标必须指定其部分相对目录路径、文件名和文件扩展名。
3	如果没有指定版本坐标，Antora 将在运行时使用目标部件组件的最新版本来完成资源 ID 。此行为仅适用于目标部分和当前页面属于不同文档组件的情况。

让我们使用组件版本 colorado 5.2 (例15)和 wyoming 1.0 (例16)的文件作为本节示例的基础。

Example 15. Example 15. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 pagesAlian (3)
      📄 index.adoc
    📂 partials (4)
      📄 treeline-warning.adoc

1	将组件版本定义为 Colorado 5.2
2	定义根(ROOT)模块
3	将后续源文件定义为页面
4	将后续源文件定义为部分文件

Example 16. Example 16. Directories and files assigned to wyoming 1.0

📄 antora.yml (1)
📂 modules
  📂 sierra-madre (2)
    📂 pagesAlian (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中的 include 指令将嵌入 treeline-warning.adoc 部分的内容到 elevation.adoc 页面中。

Example 17. Example 17. elevation.adoc (current page)

include::5.2@colorado:ROOT:partial$treeline-warning.adoc[]

如示例17所示，目标 partial 的版本坐标为 5.2 ，组件坐标为 colorado ，模块坐标为 ROOT ，族坐标为 partial$ ，文件坐标为 treeline−warning.adoc 。您还可以将 treeline−warning.adoc 的资源 ID 指定为 5.2@colorado::partial$treeline-warning.adoc（注意模块坐标 ROOT 似乎缺失了）。当指定了目标部分的组件坐标，并且目标部分属于 ROOT 模块时，就不必显式指定模块坐标 ROOT 。但是，仍必须输入紧接着模块坐标后面的冒号( : )。这种简写只在指定了组件坐标并且目标部分的模块坐标是 ROOT 时才有效。

使用一个部分的最新版本

TIP: 此行为仅适用于目标部分(partial)和当前页面属于不同文档组件的情况!

如果在分配给 include 指令的资源 ID 中没有指定版本，并且目标部分和当前页面不属于同一个组件，那么 Antora 将在运行时使用目标部分组件的最新版本的版本坐标来完成资源 ID 。

让我们使用属于组件版本 colorado 5.2 (例18)、wyoming 1.0 (例19)和 wyoming 1.5 (例20)的文件作为本节示例的基础。

Example 18. Example 18. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pagesAlian
      📄 willow-creek.adoc

1	将组件版本定义为 colorado 5.2

Example 19. Example 19. Directories and files assigned to wyoming 1.0

📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pagesAlian
      📄 elevation.adoc
    📂 partials
      📄 bears.adoc

1	将组件版本定义为 wyoming 1.0

Example 20. Example 20. Directories and files assigned to wyoming 1.5

📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pagesAlian
      📄 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中显示了一个从 willow-creek.adoc （当前页面）引用 bears.adoc （目标部分）的 include 指令。请注意，目标部分的版本坐标未指定。

Example 21. Example 21. willow-creek.adoc (current page)

include::wyoming:sierra-madre:partial$bears.adoc[]

当 Antora 运行时，根据其版本排序规则和最新版本标准，它将标识 wyoming 1.5 为 wyoming 组件的最新版本。因为示例21中未指定版本坐标，所以 Antora 将使用最新的 wyoming 组件的版本坐标 1.5 完成分配给 include 指令的资源 ID 。

WARNING: 此链接到最新版本的行为仅适用于未指定版本坐标并且目标部分和当前页面属于不同组件的情况。如果在资源 ID 中没有指定版本和组件坐标，则 Antora 假定目标部分与当前页面属于相同的组件版本，并使用当前页面的版本和组件坐标来完成目标部分的资源 ID 。

包含指令放置位置

include 指令放在新行开头。当你在 include 指令的上方和下方输入空行时，目标部分的内容将作为一个独立的块显示。您可以将目标部分中的内容附加到当前页面中的块中，方法是将 include 指令放在与应该附加的内容直接相邻的新行上。

Example 22. Example 22. current-page.adoc

A paragraph in the page.

include::partial$cli-options.adoc[tag=compass] (1)

A line of content.
include::partial$addendum.adoc[] (2)
Another line of content.

1	要将包含的内容显示为一个独立的块，请确保在 `include` 指令上方和 `include` 指令之后有一个空行。
2	若要将包含的内容附加到当前页面中的块上，请在块的内容行正上方、中间或下方的新行上输入 `include` 指令。

包含图源

如果您在页面中使用从源代码生成的图表，您可能希望将图表的源代码存储在一个单独的文件中。是将该源存储为示例还是部分存储由您决定。由于源代码不是代码示例，因此部分代码似乎更符合逻辑。

创建一个名为 diagrams 的文件夹，放在 partials 目录下。然后将您的图表源存储在该文件夹中。假设文件名为 partials/diagrams/my-schema.puml 。现在您可以按以下方式将该源包含到页面中：

Example 23. Example 23. Include the source of a diagram

[plantuml,my-schema,svg]
....
include::partial$diagrams/my-schema.puml[]
....

您可以在其他模块、版本或组件中引用图源，就像使用其他部分一样。

了解更多

AsciiDoc 和 Asciidoctor 资源