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.

Insert an example into a page

Example 1 shows the structure of an include directive with a example’s fully qualified resource ID.

Example 1. Include directive and resource ID syntax
include::version@component:module:example$filename.ext[]

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

The steps below assume that the target example and current page belong to the same component version and module, so only the family (example$) and resource coordinates of the target example resource are entered in the resource ID.

  1. On a new line, enter the name of the directive followed by two colons, include::.

    include::
  2. Enter the resource ID of the target example file, making sure to specify the example$ family coordinate.

    include::example$filename.ext

    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 your example.

  3. Complete the directive with a set of square brackets ([]).

    include::example$filename.ext[]
  4. The brackets can contain an optional list of attributes. The attributes are entered as key-value pairs separated by commas.

    include::example$filename.ext[attribute,attribute]

Antora supports filtering the lines of an example file by either line numbers using the lines attribute or tags using the tag or tags attributes. Filtering by line numbers takes precedence. See the AsciiDoc include directive documentation for full details about the lines, tag, and tags syntax.

Include an example from the same module

When the target example file and the current page belong to the same module, you only need to enter the family and resource coordinates in the resource ID.

Example 2. current-page.adoc
include::example$helloworld.java[]

Include an example from another module

When the target example file and current page belong to different modules of the same component version, enter the example’s module, family, and resource coordinates in the resource ID.

Example 3. current-page.adoc
include::ROOT:example$output/query-max.json[]

Include an example from another component

When the target example file and the current page belong to different docs components, enter the example’s version, component, module, family, and resource coordinates in the resource ID.

Example 4. current-page.adoc
include::4.5@uml:admin:example$config.js[]

Don’t specify the version coordinate if you want the page to always reference the latest version of the example.

Example 5. current-page.adoc
include::uml:admin:example$config.js[]