Include Content

You can use the include directive (include::[]) to insert content from one file into an AsciiDoc file. You can include a partial, a standard page, or an example file. Partial and standard pages are AsciiDoc files; examples are often other file types, such as source code or data values.

There are a few things to know about using the include directive in the Antora environment, which this page covers.

Include a partial

To include a partial AsciiDoc file into a standard page, use the include directive with a target starting with the attribute reference {partialsdir}, followed by the relative path of the partial file.

Insert a partial page using an include directive
include::{partialsdir}/log-definition.adoc[]

Let’s break this down.

  1. On its own line, start with the include directive prefix, include::.

  2. Next comes the target. Start the target with {partialsdir}; this tells Antora to look for the file in the pages/_partials directory inside the current module.

  3. Then enter the relative path of the partial directly after the reference.

  4. Close the directive with a pair of square brackets ([]). The brackets can contain an optional list of attributes such as leveloffset and tags. The attributes should be entered as key=value pairs separated by commas.

Partial AsciiDoc files should be saved in the pages/_partials directory inside the current module. Antora knows the path to the partials directory, so you don’t need to set it in the header of your AsciiDoc file. When viewing the file in a preview tool, the path is managed by the adjacent _attributes.adoc file.

Currently, Antora only supports filtering includes by tags.

Include a standard page

Instead of using a partial, you can insert the contents of a standard page into another standard page.

Insert a standard page using the include directive
include::other-page.adoc[]
  1. On its own line, start with the include directive prefix, include::.

  2. Next comes the target. The target is the path of the page being included relative to the current page.

  3. Close the directive with a pair of square brackets ([]). The brackets can contain an optional list of attributes such as leveloffset and tags. The attributes should be entered as key=value pairs separated by commas.

If you include a standard page (a page that is stored in the pages directory) into another page, you must set the page-partial AsciiDoc attribute in the document header of the page being included.

A standard page included in another standard page
= Other Page
:page-partial:

Page contents.

This attribute lets Antora know that you intend to include the AsciiDoc source of the file into another AsciiDoc file.

Include an example

So far we’ve only talked about including AsciiDoc in AsciiDoc. You can also use the include directive to insert non-AsciiDoc content into a file. One common use case is to insert source code from a file stored in the examples directory into a listing block.

In this case, you’ll use the include directive with a target starting with the attribute reference {examplesdir}, followed by the relative path of the example file.

Insert source code from the examples directory into a listing block
[source,java]
----
include::{examplesdir}/HelloWorld.java[]
----
  1. On its own line, start with the include directive prefix, include::.

  2. Next comes the target. Start the target with {examplesdir}; this tells Antora to look for the file in the examples directory inside the current module.

  3. Then put the relative path of the example file directly after the reference.

  4. Close the directive with a pair of square brackets ([]). The brackets can contain an optional list of attributes such as tags and indent. The attributes should be entered as key=value pairs separated by commas.

Currently, all of the example files you want to include must live in the examples directory inside the current module. In the future, it will be possible to pull in example source code and files from other locations.

Like with partials, Antora knows the path to the examples directory, so you don’t need to set it in the header of your AsciiDoc file. When viewing the file in a preview tool, the path is managed by the adjacent _attributes.adoc file.

Antora doesn’t yet support filtering includes by line number, only by tags.

Asciidoctor resources