Include an Example

Examples are non-AsciiDoc files that contain reusable content, such as source code or data values, that are often inserted into listing blocks. Examples are saved in the examples directory. Typically, an example and the standard page it’s used in are stored in the same module. However, regardless of an example’s source module, it can be inserted into any standard page in your documentation site using the include directive and the example file’s resource ID.

Include directive structure for examples

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

include::version@component:module:example$name-of-file.ext[optional attributes]
  1. On a new line, enter the directive name followed by two colons, include::.

    include::version@component:module:example$name-of-file.ext[optional attributes]
  2. Enter the resource ID of the example file. An example’s resource coordinates are determined just like the coordinates in an xref.

    include::version@component:module:example$name-of-file.ext[optional attributes]
  3. The resource ID must contain the example$ family.

    include::version@component:module:example$name-of-file.ext[optional attributes]
  4. Close the directive with a set of square brackets ([]). The brackets can contain an optional list of attributes such as indent and tags. The attributes should be entered as key=value pairs separated by commas.

    include::version@component:module:example$name-of-file.ext[optional attributes]
Currently, Antora only supports filtering includes by tags.

Include an example from the same module

When the example file and the standard page file belong to the same module, you only need to enter the family name (example$) and the name of the example file.

[source,java]
----
include::example$HelloWorld.java[]
----

Include an example from another module

When the example and the page belong to the same component, but different modules, enter the example’s module, family (example$), and the name of the example file.

[source,json]
----
include::ROOT:example$output/query-max.json[]
----

Include an example from another component

When the example and page belong to different components, enter the example’s component, module, family (example$), and the name of the example file.

[source,javascript]
----
include::uml:admin:example$tour/config.js[]  (1)
[...]

include::4.5@tree::example$extension.js[] (2)
----
1 When including an example from another component, the include directive will use the example file from the latest stable version of its component unless a version coordinate is specified.
2 Enter the version coordinate to use a specific version of an example.