Include an Example

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

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

An include directive consists of the directive’s prefix (include::), the resource ID of the target example, and a set of square brackets ([]). You can specify optional attributes within the square brackets as key-value pairs separated by commas. The target example is the source file of an example that’s being referenced by the current page. The target example 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 example.

When Antora runs, content from the target example is inserted into the current page at the location where the include directive is entered. The target example’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 example.

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

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

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

Also, you’ll need to specify additional resource ID coordinates when the target example 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 example and the current page don’t belong to the same module, you must specify the target example’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 warm-up.js example into the index.adoc page. That means the source file warm-up.js is the target example and index.adoc is the current page. As shown in Example 12 above, the index.adoc page belongs to the testing module, and the warm-up.js example belongs to the ROOT module.

Example 13 shows an include directive in index.adoc that references the example warm-up.js. The module, example$, and file coordinates of the target example are assigned to the include directive.

As shown in Example 13, the target example’s module coordinate is ROOT, its family coordinate is example$, and its file coordinate is warm-up.js.

When the target example and current page don’t belong to the same documentation component, specify the example’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 mapper 8.0 (Example 15) and grid-twist 2.5 (Example 16) as the basis for the example in this section.

Using files from Example 15 and Example 16, let’s reference warm-up.js (target example) from interface-loader.adoc (current page). The warm-up.js example belongs to the component version mapper 8.0. The interface-loader.adoc page belongs to the component version grid-twist 2.5.

The include directive in Example 17 will embed the content of the warm-up.js example into the interface-loader.adoc page.

As shown in Example 17, the target example’s version coordinate is 8.0, its component coordinate is mapper, its module coordinate is ROOT, its family coordinate is example$, and its file coordinate is warm-up.js. You could also specify the resource ID for warm-up.js as 8.0@mapper::example$warm-up.js (notice the module coordinate ROOT seems to be missing). When the target example’s component coordinate is specified, and the target example 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 example is ROOT.