Include a Page

You can include another page or a portion of another page into the current page using the AsciiDoc include directive.

Overview

In Antora, the AsciiDoc include directive has been configured to include pages from the content catalog. You can include a page from anywhere in the site, including pages from a different component, component version, or module.

In the simplest form, the target can be a path relative to the current page:

include::./relative-page.adoc[<attrlist>]

The target can also be a page ID. The page ID ranges in scope from a page in the current module (starting from the root of the pages family):

include::page$page.adoc[<attrlist>]

to a page in a topic in a module of different component version:

include::version@component:module:page$topic/page.adoc[<attrlist>]

Let’s explore the syntax of the include directive in detail.

Syntax walkthrough

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

    include::

  2. Next, enter the relative path or resource ID of the target page (i.e., page ID) in the target slot.

    Target as relative path

    A relative path include is resolved from the current page (not the root of the pages family). The relative path must be prefixed with ./.

    include::./relative-page.adoc[]
    You may find that the relative path works without this prefix, but that could change in the future.
    Target as resource ID

    A resource ID include is resolved much like the target of an xref. There are two key differences:

    1. A relative path (normally the shortest form of a resource ID) is not, in fact, treated as a resource ID. Instead, it’s resolved from the directory of the current page.

    2. A resource ID must include the page$ family segment since the include directive can also be used to include files from other families. The presence of the family segment forces the target to be treated as a resource ID, specifically a page ID (e.g., page$name-of-page.adoc).

    Like in the xref macro, all other segments (component, version, and module) are optional and will assume the context of the current page.

    include::version@component:module:page$topic/page.adoc[]

  3. Close the directive using a set of square brackets ([]).

    include::version@component:module:page$topic/page.adoc[]

    The brackets may contain an optional list of attributes (represented in the previous examples by <attrlist>). Include attributes should be entered as key=value pairs separated by commas.

    include::version@component:module:page$topic/page.adoc[tag=definition]

    All the attributes (e.g., lines, tags, leveloffset, indent) on the include directive are supported.

Antora supports filtering the lines of an include 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 and tag or tags syntax.

The page-partial attribute

As Antora processes each page, it converts the contents of the file from AsciiDoc to HTML. (Within a component version, pages are typically processed in order by module and relative filename). The conversion of the contents from AsciiDoc to HTML would normally impact the behavior of the include directive. Specifically, a page that uses the include directive to include a page that has already been processed would see HTML instead of AsciiDoc.

To rectify this ordering problem, Antora can retain the AsciiDoc source until all pages have been converted. This behavior is activated by setting the page-partial attribute in the document header of the page. As of Antora 2.2, the page-partial attribute is (soft) set globally by default. (Soft set means the it can still be overridden by the page). So, really, you don’t even have to think of it. It will just work.

The downside of retaining the AsciiDoc source is that it may increase the peak heap usage of Antora for very large sites by ~ 10%. If that’s a concern, you can revert to the previous “a la carte” behavior. To revert to the previous behavior (prior to Antora 2.2), set the following property in the playbook file:

asciidoc:
  attributes:
    page-partial: false

The page-partial attribute will no longer be set globally. Now you must set the page-partial attribute on any page you want to use in an include directive. For example:

= Shared Page
:page-partial:

Page contents.

With the page-partial attribute set, you can safely refer to that page using the include directive:

\include:shared-page.adoc[]

Recall that the page-partial attribute in the included page instructs Antora to retain the AsciiDoc source until all pages have been converted.

Learn more

Asciidoctor resources