Include a Page

A page or portion of a page can be inserted into any other page in your site using the AsciiDoc include directive and the page’s resource ID.

AsciiDoc include directive for pages

An AsciiDoc include directive inserts content from the source file of a page into another page. The include directive accepts the Antora resource ID of partials, examples, and pages as a value.

Example 1 shows the structure of an include directive with the fully qualified resource ID of a page. By default, the include directive assumes the family coordinate is page$ when a family coordinate isn’t specified.

Example 1. Include directive assigned the fully qualified resource ID of a page

include::version@component:module:file-coordinate-of-target-page.adoc[optional attribute]

An include directive consists of the directive’s prefix (include::), the resource ID of the target page, and a set of square brackets ([]). You can specify optional attributes within the square brackets as key-value pairs separated by commas. The target page is the source file of a page that’s being referenced by the current page. The target page 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 page.

When Antora runs, the source content from the target page is inserted into the current page at the location where the include directive is entered. The target page’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 page. See Current page context and structure to learn more.

Insert a page into a page

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

In your IDE or plain text editor, open the page where you want to include content from the target page. For this step and the subsequent steps, let’s assume you’ve opened the file ranges.adoc.
Example 2. ranges.adoc (current page)
There are three mountain passes in the Sawatch Range.
The current page, ranges.adoc, belongs to the component version colorado 5.2 and module ROOT, shown in Example 3.
Example 3. Directories and files assigned to colorado 5.2
📄 antora.yml (1) 📂 modules 📂 ROOT (2) 📂 pages (3) 📄 cottonwood-pass.adoc 📄 index.adoc 📄 ranges.adoc
1 Defines the component version as colorado 5.2

2 Defines the ROOT module

3 Defines subsequent files as pages
In the current page, select the line where you want the page’s content to be inserted. At the beginning of the line, enter the name of the directive followed by two colons, include::.
Example 4. ranges.adoc (current page)
```
There are three mountain passes in the Sawatch Range.

include::
```

Let’s reference the target page, cottonwood-pass.adoc, from the current page. Assign the resource ID of the target page to the include directive. Both cottonwood-pass.adoc and ranges.adoc belong to the same component version and module (see Example 3). Therefore, only the file coordinate of the target page needs to be specified.

Example 5. ranges.adoc (current page)

There are three mountain passes in the Sawatch Range.

include::cottonwood-pass.adoc

The file coordinate for the cottonwood-pass.adoc page is cottonwood-pass.adoc. The target page’s file coordinate consists solely of its filename and file extension because cottonwood-pass.adoc is stored at the root of the pages directory.

You can specify the page$ family coordinate in the resource ID if you prefer, but it isn’t required when including a page into a page. The include directive assumes the family coordinate is page$ when it isn’t specified.

Directly after the resource ID of the target page, complete the directive with a set of square brackets ([]).
Example 6. ranges.adoc (current page)
There are three mountain passes in the Sawatch Range. include::cottonwood-pass.adoc[]
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 page into the current page.

The structure of the target page’s file coordinate varies depending on whether the target page is stored at the root of the pages family directory, like in the preceding instructions, or in a subdirectory of the pages directory.

Example 7. current-page.adoc

include::target-page-filename.adoc[] (1)

include::path/to/target-page-filename.adoc[] (2)

include::./target-page-filename.adoc[] (3)

1	File coordinate of the target page when it’s stored at the root of the pages directory.
2	File coordinate of the target page when it’s stored in a subdirectory of the pages directory.
3	File coordinate of the target page when the target page and current page are stored in the same subdirectory of the pages directory.

The following sections describe how to specify a file coordinate with a pages-relative directory path or relative path token. Also, you’ll need to specify additional resource ID coordinates when the target page and current page don’t belong to the same module or component version.

File coordinate with pages-relative directory path

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

Example 8. File coordinate when the target page is stored in a subdirectory of a pages directory

include::path/to/target-page-filename.adoc[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 colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 pages (3)
      📄 cottonwood-pass.adoc
      📄 index.adoc
      📄 ranges.adoc
      📂 supplies (4)
        📄 gear.adoc
        📄 safety.adoc

1	Defines the component version as colorado 5.2
2	Defines the ROOT module
3	Defines subsequent files as pages
4	A subdirectory in pages containing the source files of pages

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

Example 10. cottonwood-pass.adoc (current page)

== Trip planning

include::supplies/safety.adoc[]

As shown in Example 10, the file coordinate for safety.adoc is supplies/safety.adoc.adoc. The file coordinate for safety.adoc consists of its pages-relative directory path, filename, and file extension because it’s stored in the subdirectory supplies while the current page, cottonwood-pass.adoc, is stored in the pages directory. If the current page and target page were stored in the same subdirectory, you could use the relative path token, ./, in place of the pages-relative directory path.

File coordinate with relative path token

If the target page and current page are stored in the same subdirectory within the pages directory, the pages-relative directory path of the target page’s file coordinate can be replaced with the relative path token, ./.

Example 11. File coordinate in include directive when the target page and current page are stored in the same subdirectory

include::./target-page-filename.adoc[]

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

Example 12. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 pages (3)
      📄 cottonwood-pass.adoc
      📄 index.adoc
      📄 ranges.adoc
      📂 supplies (4)
        📄 gear.adoc
        📄 safety.adoc

1	Defines the component version as colorado 5.2
2	Defines the ROOT module
3	Defines subsequent files as pages
4	A subdirectory in pages containing the source files of pages

Let’s reference gear.adoc from safety.adoc. Example 12 shows that both files are stored in the supplies subdirectory of the pages directory, and that both files belong to the ROOT module of the same component version. When the target page and current page are stored in the same subdirectory within the pages directory, the relative path token, ./, can be used to abbreviate the target page’s file coordinate.

In Example 13, the include directive in the safety.adoc page (current page) references the gear.adoc page (target page).

Example 13. safety.adoc (current page)

include::./gear.adoc[]

As shown in Example 13, the file coordinate for gear.adoc, when referenced from safety.adoc, is ./gear.adoc. Both pages are stored in the supplies subdirectory, therefore, the pages-relative directory path of the target page’s file coordinate is replaced with the ./ token.

You may find that the include directive resolves the target page when the ./ token isn’t used in the file coordinate. However, we strongly recommend using the ./ token when referencing a target page that is stored in the same subdirectory as the current page.

Embed a page from another module or component version

You can include a page from any module or component version into another page that belongs to your site by assigning the target page’s module coordinate or version, component, and module coordinates, respectively, to the include directive.

Example 14. current-page.adoc

include::module:file-coordinate-of-target-page.adoc[] (1)

include::version@component:module:file-coordinate-of-target-page.adoc[] (2)

include::component:module:file-coordinate-of-target-page.adoc[] (3)

1	Assign the module and file coordinates of the target page to the include directive when the target page and current page belong to the same component version but not the same module.
2	Assign the version, component, module, and file coordinates of the target page to the include directive when the target page and current page don’t belong to the same component version.
3	If the version coordinate isn’t specified, Antora uses the latest version of the target page’s component to complete the resource ID at runtime. This behavior only applies when the target page and current page belong to different docs components.

For example, to embed the content of cottonwood-pass.adoc (target page) into a page (current page) that belongs to a different module of the colorado 5.2 component version, specify the target page’s module coordinate in the include directive.

Example 15. current-page.adoc

include::ROOT:cottonwood-pass.adoc[]

If the current page belongs to a different component version than cottonwood-pass.adoc (target page), specify the target page’s version, component, module, and file coordinates.

Example 16. current-page.adoc

include::5.2@colorado:ROOT:cottonwood-pass.adoc[]

As shown in Example 16, the target page’s version coordinate is 5.2, its component coordinate is colorado, its module coordinate is ROOT, and its file coordinate is cottonwood-pass.adoc.

Include directive placement

An include directive is placed at the beginning of a new line. The content from the target page will be displayed as a standalone block when you enter an empty line above and below the include directive. You can attach content from the target page to a block in the current page by placing the include directive on a new line directly adjacent to the content to which it should be attached.

Example 17. current-page.adoc

A paragraph in the page.

include::resource-id-of-target-page.adoc[tag=value] (1)

A line of content.
include::resource-id-of-target-page.adoc[] (2)
Another line of content.

1	To display the included content as a standalone block, make sure there is an empty line before the include directive and after the include directive.
2	To attach the included content to a block in the current page, enter the include directive on a new line directly above, between, or below the content lines of the block.

Learn more

AsciiDoc and Asciidoctor resources