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.

AsciiDoc include directive

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$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 example$ and resource coordinates of the target example resource are entered in the resource ID.

On a new line, enter the name of the directive followed by two colons, include::.
```
include::
```
Enter the resource ID of the target example file. The resource ID must specify the example$ family coordinate since the include directive is also used to insert files from other families.
```
include::example$example-filename.ext
```
Close the directive with a set of square brackets ([]).
```
include::example$example-filename.ext[]
```
The brackets can contain an optional list of attributes. The attributes are entered as key-value pairs separated by commas.
```
include::example$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 Asciidoctor documentation for full details of 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 (example$) 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 (example$), 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 (example$), 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 a page to always reference the latest version of the example.

Example 5. current-page.adoc

include::uml:admin:example$config.js[]

Learn more

Asciidoctor resources