Include an Example

An example can be inserted into any page or partial in your site using the AsciiDoc include directive and the example’s resource ID.

If you aren’t familiar with the Antora resource ID and its coordinates, see:

AsciiDoc include directive for examples

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.

Example 1. Include directive assigned the fully qualified resource ID of an example
include::version@component:module:example$file-coordinate-of-target-example.ext[optional attribute]

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.

Insert an example into a page

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

  1. In your IDE or plain text editor, open the page where you want to insert the example. For this step and the subsequent steps, let’s assume you’ve opened the file phases.adoc.

    Example files are often inserted into source blocks. Example 2 shows a source block with a title and an assigned language set up in the current page.

    Example 2. phases.adoc (current page)
    .First test phase
    [,js]
    ----
    
    ----

    The current page, phases.adoc, belongs to the component version mapper 8.0 and module testing, shown in Example 3.

    Example 3. Directories and files assigned to mapper 8.0
    📄 antora.yml (1)
    📂 modules
      📂 testing (2)
        📂 examples (3)
          📄 timer.js
        📂 pages (4)
          📄 index.adoc
          📄 phases.adoc
    1 Defines the component version as mapper 8.0
    2 Defines the testing module
    3 Defines subsequent files as examples
    4 Defines subsequent files as pages
  2. In the current page, select the line where you want the example’s content to be inserted. At the beginning of the line, enter the name of the directive followed by two colons, include::.

    Example 4. phases.adoc (current page)
    .First test phase
    [,js]
    ----
    include::
    ----
  3. Let’s reference the target example, timer.js, from the current page. Assign the resource ID of the target example to the include directive. Both timer.js and phases.adoc belong to the same component version and module (see Example 3). Therefore, only the example$ family coordinate and file coordinate of the target example need to be specified.

    Example 5. phases.adoc (current page)
    .First test phase
    [,js]
    ----
    include::example$timer.js
    ----

    The file coordinate for the timer.js example is timer.js. The target example’s file coordinate consists solely of its filename and file extension because timer.js is stored at the root of the examples directory.

    By default, the include directive assumes the family coordinate is page$ when the coordinate isn’t specified. If you forget to use the example$ coordinate, Antora will report an error because it won’t be able to find the example.
  4. Directly after the resource ID of the target example, complete the directive with a set of square brackets ([]).

    Example 6. phases.adoc (current page)
    .First test phase
    [,js]
    ----
    include::example$timer.js[]
    ----

    The brackets of the include directive can contain an optional list of attributes, such as lines, tag, or tags. The attributes are entered as key-value pairs separated by commas. See the AsciiDoc include directive documentation for full details about the lines, tag, and tags syntax.

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.

Example 7. current-page.adoc
include::example$target-example-filename.ext[] (1)

include::example$path/to/target-example-filename.ext[] (2)

include::example$./target-example-filename.ext[] (3)
1 File coordinate of the target example when it’s stored at the root of the examples directory.
2 File coordinate of the target example when it’s stored in a subdirectory of the examples directory.
3 File coordinate of the target example when the target example and current page are stored in subdirectories with parallel family-relative directory paths. This is an advanced use case.

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.

File coordinate with examples-relative directory path

The examples-relative directory path of the target example is required in its file coordinate when it’s stored in a subdirectory of the examples directory.

Example 8. File coordinate when the target example is stored in a subdirectory of an examples directory
include::example$path/to/target-example-filename.ext[optional attribute]

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

Example 9. Directories and files assigned to grid-twist 2.5
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📂 providers (4)
        📄 job.yml
    📂 pages (5)
      📄 interface-loader.adoc
1 Defines the component version as grid-twist 2.5
2 Defines a module named ROOT
3 Defines subsequent files as examples
4 A subdirectory in examples containing the source files of examples
5 Defines subsequent files as pages

Let’s reference job.yml from interface-loader.adoc. As you can see in Example 9 above, the example and page belong to the ROOT module. In Example 10, an include directive in the interface-loader.adoc page (current page) references the job.yml file (target example).

Example 10. interface-loader.adoc (current page)
[,yaml]
----
include::example$providers/job.yml[]
----

As shown in Example 10, the family coordinate is example$ and the file coordinate for job.yml is providers/job.yml. The file coordinate for job.yml consists of its examples-relative directory path, filename, and file extension because it’s stored in the subdirectory providers.

In special circumstances where the examples-relative directory path of the target example and the pages-relative directory path of the current page are parallel, the examples-relative directory path can be replaced with the relative path token, ./.

Include an example from another module

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.

Example 11. Module, family, and file coordinates assigned to an include directive
include::module:example$target-example-filename.ext[optional attribute] (1)

include::module:example$path/to/target-example-filename.ext[optional attribute] (2)
1 Assign the module, example$, and file coordinates of the target example to the include directive when the target example and current page belong to the same component version but not the same module. The target example’s file coordinate is its filename and file extension when it’s stored at the root of a examples family directory.
2 If the target example is stored in a subdirectory of a examples directory, the target example’s file coordinate must specify its examples-relative directory path, filename, and file extension.

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

Example 12. Directories and files assigned to mapper 8.0
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 Defines the component version as mapper 8.0
2 Defines the ROOT module
3 Defines subsequent files as examples
4 Defines the testing module
5 Defines subsequent files as examples
6 Defines subsequent files as pages

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.

Example 13. index.adoc (current page)
[,js]
----
include::ROOT:example$warm-up.js[]
----

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.

Include an example from another component

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.

Example 14. Version, component, module, family, and file coordinates assigned to an include directive
include::version@component:module:example$target-example-filename.ext[] (1)

include::version@component:module:example$path/to/target-example-filename.ext[] (2)

include::component:module:example$file-coordinate-of-target-example.ext[] (3)
1 Assign the version, component, module, family, and file coordinates of the target example to the include directive when the target example and current page don’t belong to the same component version. The target example’s file coordinate is its filename and file extension when the target example is stored at the root of a examples family directory.
2 If the target example is stored in a subdirectory of a examples directory, the target example’s file coordinate must specify its examples-relative directory path, filename, and file extension.
3 If the version coordinate isn’t specified, Antora uses the latest version of the target example’s component to complete the resource ID at runtime. This behavior only applies when the target example and current page belong to different docs components.

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.

Example 15. Directories and files assigned to mapper 8.0
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 Defines the component version as mapper 8.0
2 Defines the ROOT module
3 Defines subsequent files as examples
4 Defines the testing module
5 Defines subsequent files as examples
6 Defines subsequent files as pages
Example 16. Directories and files assigned to grid-twist 2.5
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📂 providers (4)
        📄 job.yml
    📂 pages (5)
      📄 interface-loader.adoc
1 Defines the component version as grid-twist 2.5
2 Defines a module named ROOT
3 Defines subsequent files as examples
4 A subdirectory in examples containing the source files of examples
5 Defines subsequent files as pages

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.

Example 17. interface-loader.adoc (current page)
[,js]
----
include::8.0@mapper:ROOT:example$warm-up.js[]
----

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.

Use the latest version of an example

This behavior only applies when the target example and current page belong to different docs components!

If a version isn’t specified in the resource ID assigned to an include directive, and the target example and current page don’t belong to the same component, Antora uses the version coordinate of the latest version of the target example’s component to complete the resource ID at runtime.

Let’s use the files that belong to the component versions mapper 8.0 (Example 18), mapper 8.1 (Example 19), and grid-twist 2.5 (Example 20) as the basis for the example in this section.

Example 18. Directories and files assigned to mapper 8.0
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 Defines the component version as mapper 8.0
Example 19. Directories and files assigned to mapper 8.1
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 Defines the component version as mapper 8.1
Example 20. Directories and files assigned to grid-twist 2.5
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📂 providers (4)
        📄 job.yml
    📂 pages (5)
      📄 interface-loader.adoc
1 Defines the component version as grid-twist 2.5

Let’s reference the timer.js example (target example) from the interface-loader.adoc page (current page). interface-loader.adoc belongs to component version grid-twist 2.5. There are two files named timer.js that belong to the mapper component, testing module, and examples family. One timer.js belongs to version 8.0, the other timer.js to version 8.1.

Example 21 shows an include directive referencing timer.js (target example) from interface-loader.adoc (current page). Notice that the target example’s version coordinate isn’t specified.

Example 21. interface-loader.adoc (current page)
[,js]
----
include::mapper:testing:example$timer.js[]
----

When Antora runs, it will identify mapper 8.1 as the latest version of the mapper component according to its version sorting rules and latest version criteria. Because a version coordinate isn’t specified in Example 21, Antora will complete the resource ID assigned to the include directive using the version coordinate — 8.1 — from the latest mapper component.

This behavior of linking to the latest version only applies when the version coordinate is unspecified and the target example and current page belong to different components. If the version and component coordinates aren’t specified in the resource ID, Antora assumes the target example belongs to the same component version as the current page and uses the current page’s version and component coordinates to complete the target example’s resource ID.