Include a Partial

An AsciiDoc include directive inserts content from a partial’s source file into another partial or a page. The include directive accepts the Antora resource ID of partials, examples, and pages as a value.

Example 1 shows the structure of an include directive with the fully qualified resource ID of a partial. Because the include directive is used to reference other resources, the partial$ family coordinate must be specified in the partial’s resource ID when it’s assigned to an include directive.

At a minimum, an include directive consists of the directive’s prefix (include::), the resource ID of the target partial, and a set of square brackets ([]). You can specify optional attributes within the square brackets as key-value pairs separated by commas. The target partial is the source file of a partial that’s being referenced by the current page. The target partial is referenced by assigning its resource ID to an include directive in the content of the current page. The current page is the page source file containing the include directive that references the target partial.

When Antora runs, content from the target partial is inserted into the current page at the location where the include directive is entered. The target partial’s content is converted after it’s inserted into the current page. This means the current page’s component version, module, attributes, and other elements are applied to or may impact the content included from the target partial. See Current page context and structure to learn more.

Let’s break down the AsciiDoc include directive and resource ID coordinates you need to insert a target partial into the current page.

That’s it! You’ve created an include directive that will insert the target partial into the current page.

The preceding instructions showed you how to insert a partial into a page under the most common scenario—​the target partial and current page belong to the same component version and module and the target partial is stored at the root of a partials folder. However, if the target partial is stored in a subdirectory of the partials directory, its file coordinate must specify the partials-relative directory path in addition to its filename and file extension.

Also, you’ll need to specify additional resource ID coordinates when the target partial and current page don’t belong to the same module or component version. The following sections provide examples showing the various resource ID scenarios.

When the target partial and the current page don’t belong to the same module, you must specify the target partial’s module, family, and file coordinates in the include directive.

Let’s use the files that belong to the component version shown in Example 12 as the basis for the example in this section.

Let’s insert the treeline-warning.adoc partial into the ridge.adoc page. That means the source file treeline-warning.adoc is the target partial and ridge.adoc is the current page. As shown in Example 12 above, the ridge.adoc page belongs to the la-garita module, and the treeline-warning.adoc partial belongs to the ROOT module.

Example 13 shows an include directive in ridge.adoc that references the partial treeline-warning.adoc. The module, partial$, and file coordinates of the target partial are assigned to the include directive.

As shown in Example 13, the target partial’s module coordinate is ROOT, its family coordinate is partial$, and its file coordinate is treeline-warning.adoc.

When the target partial and current page don’t belong to the same documentation component, specify the partial’s version, component, module, family, and file coordinates in the resource ID assigned to the include directive.

Let’s use the files that belong to the component versions colorado 5.2 (Example 15) and wyoming 1.0 (Example 16) as the basis for the example in this section.

Using files from Example 15 and Example 16, let’s reference treeline-warning.adoc (target partial) from elevation.adoc (current page). The treeline-warning.adoc partial belongs to the component version colorado 5.2. The elevation.adoc page belongs to the component version wyoming 1.0.

The include directive in Example 17 will embed the content of the treeline-warning.adoc partial into the elevation.adoc page.

As shown in Example 17, the target partial’s version coordinate is 5.2, its component coordinate is colorado, its module coordinate is ROOT, its family coordinate is partial$, and its file coordinate is treeline-warning.adoc. You could also specify the resource ID for treeline-warning.adoc as 5.2@colorado::partial$treeline-warning.adoc (notice the module coordinate ROOT seems to be missing). When the target partial’s component coordinate is specified, and the target partial belongs to the ROOT module, the module coordinate ROOT doesn’t have to be explicitly specified. However, you must still enter the colon (:) that would follow the module coordinate. This shorthand only works when a component coordinate is specified and the module coordinate of the target partial is ROOT.

An include directive is placed at the beginning of a new line. The content from the target partial will be displayed as a standalone block when you enter an empty line above and below the include directive. You can attach content from the target partial to a block in the current page by placing the include directive on a new line directly adjacent to the content to which it should be attached.