Include a Partial

A partial can be inserted into any page or another partial in your site using the AsciiDoc include directive and the partial’s resource ID.

If you aren’t familiar with the Antora resource ID and its coordinates, see:

AsciiDoc include directive for partials

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

Although a partial is typically an AsciiDoc fragment, a partial can be any text document with no restriction on the file’s extension. If the partial is not AsciiDoc, you have to be sure you’re inserting into a place in the AsciiDoc document that accepts non-AsciiDoc content, such as a diagram block, a code block, or CSV table. If the partial is a code example, you’re encouraged to store it as an example rather than a partial since an example is a specialized form of a partial. This page focuses on partials which are AsciiDoc files.

Example 1 shows the structure of an include directive with the fully qualified resource ID of a partial. Because the include directive is used to reference other resources, the partial$ family coordinate must be specified in the partial’s resource ID when it’s assigned to an include directive.

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

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

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

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

Insert a partial into a page

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

In your IDE or plain text editor, open the page where you want to insert the partial. For this step and the subsequent steps, let’s assume you’ve opened the file ranges.adoc.
Example 2. ranges.adoc (current page)
= Hike the Ranges == Terrain Above the treeline, the trail becomes a hard scramble.
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) 📄 index.adoc 📄 ranges.adoc 📂 partials (4) 📄 treeline-warning.adoc
1 Defines the component version as colorado 5.2

2 Defines the ROOT module

3 Defines subsequent files as pages

4 Defines subsequent files as partials
In the current page, select the line where you want the partial’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)
```
Above the treeline, the trail becomes a hard scramble.

include::
```

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

Example 5. ranges.adoc (current page)

Above the treeline, the trail becomes a hard scramble.

include::partial$treeline-warning.adoc

The file coordinate for the treeline-warning.adoc partial is treeline-warning.adoc. The target partial’s file coordinate consists solely of its filename and file extension because treeline-warning.adoc is stored at the root of the partials directory.

By default, the include directive assumes the family coordinate is page$ when the coordinate isn’t specified. If you forget to use the partial$ coordinate, Antora will report an error because it won’t be able to find the partial.

Directly after the resource ID of the target partial, complete the directive with a set of square brackets ([]).
Example 6. ranges.adoc (current page)
Above the treeline, the trail becomes a hard scramble. include::partial$treeline-warning.adoc[]
The brackets of the include directive can contain an optional list of attributes, such as lines, tag, or tags. 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 partial into the current page.

The preceding instructions showed you how to insert a partial into a page under the most common scenario—the target partial and current page belong to the same component version and module and the target partial is stored at the root of a partials folder. However, if the target partial is stored in a subdirectory of the partials directory, its file coordinate must specify the partials-relative directory path in addition to its filename and file extension.

Example 7. current-page.adoc

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

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

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

1	File coordinate of the target partial when it’s stored at the root of the partials directory.
2	File coordinate of the target partial when it’s stored in a subdirectory of the partials directory.
3	File coordinate of the target partial when the target partial and current page are stored in subdirectories with parallel family-relative directory paths. This is an advanced use case.

Also, you’ll need to specify additional resource ID coordinates when the target partial and current page don’t belong to the same module or component version. The following sections provide examples showing the various resource ID scenarios.

File coordinate with partials-relative directory path

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

Example 8. File coordinate when the target partial is stored in a subdirectory of a partials directory

include::partial$path/to/target-partial-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
  📂 la-garita (2)
    📂 pages (3)
      📄 ridge.adoc
    📂 partials (4)
      📂 climate (5)
        📄 gear-list.adoc

1	Defines the component version as colorado 5.2
2	Defines a module named la-garita
3	Defines subsequent files as pages
4	Defines subsequent files as partials
5	A subdirectory in partials containing the source files of partials

Let’s reference gear-list.adoc from ridge.adoc. As you can see in Example 9 above, the partial and page belong to the la-garita module. In Example 10, an include directive in the ridge.adoc page (current page) references the gear-list.adoc file (target partial).

Example 10. ridge.adoc (current page)

== Plan your hike

include::partial$climate/gear-list.adoc[]

As shown in Example 10, the family coordinate is partial$ and the file coordinate for gear-list.adoc is climate/gear-list.adoc. The file coordinate for gear-list.adoc consists of its partials-relative directory path, filename, and file extension because it’s stored in the subdirectory climate.

In special circumstances where the partials-relative directory path of the target partial and the pages-relative directory path of the current page are parallel, the partials-relative directory path can be replaced with the relative path token, ./.

Include a partial from another module

When the target partial and the current page don’t belong to the same module, you must specify the target partial’s module, family, and file coordinates in the include directive.

Example 11. Module, family, and file coordinates assigned to an include directive

include::module:partial$target-partial-filename.adoc[optional attribute] (1)

include::module:partial$path/to/target-partial-filename.adoc[optional attribute] (2)

1	Assign the module, `partial$`, and file coordinates of the target partial to the include directive when the target partial and current page belong to the same component version but not the same module. The target partial’s file coordinate is its filename and file extension when it’s stored at the root of a partials family directory.
2	If the target partial is stored in a subdirectory of a partials directory, the target partial’s file coordinate must specify its partials-relative directory path, filename, and file extension.

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

Example 12. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 pages (3)
      📄 ridge.adoc
  📂 ROOT (4)
    📂 partials (5)
      📄 treeline-warning.adoc

1	Defines the component version as colorado 5.2
2	Defines a module named la-garita
3	Defines subsequent files as pages
4	Defines a module named ROOT
5	Defines subsequent files as partials

Let’s insert the treeline-warning.adoc partial into the ridge.adoc page. That means the source file treeline-warning.adoc is the target partial and ridge.adoc is the current page. As shown in Example 12 above, the ridge.adoc page belongs to the la-garita module, and the treeline-warning.adoc partial belongs to the ROOT module.

Example 13 shows an include directive in ridge.adoc that references the partial treeline-warning.adoc. The module, partial$, and file coordinates of the target partial are assigned to the include directive.

Example 13. ridge.adoc (current page)

include::ROOT:partial$treeline-warning.adoc[]

As shown in Example 13, the target partial’s module coordinate is ROOT, its family coordinate is partial$, and its file coordinate is treeline-warning.adoc.

Include a partial from another component

When the target partial and current page don’t belong to the same documentation component, specify the partial’s version, component, module, family, and file coordinates in the resource ID assigned to the include directive.

Example 14. Version, component, module, family, and file coordinates assigned to an include directive

include::version@component:module:partial$target-partial-filename.adoc[] (1)

include::version@component:module:partial$path/to/target-partial-filename.adoc[] (2)

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

1	Assign the version, component, module, family, and file coordinates of the target partial to the include directive when the target partial and current page don’t belong to the same component version. The target partial’s file coordinate is its filename and file extension when the target partial is stored at the root of a partials family directory.
2	If the target partial is stored in a subdirectory of a partials directory, the target partial’s file coordinate must specify its partials-relative directory path, filename, and file extension.
3	If the version coordinate isn’t specified, Antora uses the latest version of the target partial’s component to complete the resource ID at runtime. This behavior only applies when the target partial and current page belong to different docs components.

Let’s use the files that belong to the component versions colorado 5.2 (Example 15) and wyoming 1.0 (Example 16) as the basis for the example in this section.

Example 15. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 pages (3)
      📄 index.adoc
    📂 partials (4)
      📄 treeline-warning.adoc

1	Defines the component version as colorado 5.2
2	Defines the ROOT module
3	Defines subsequent source files as pages
4	Defines subsequent source files as partials

Example 16. Directories and files assigned to wyoming 1.0

📄 antora.yml (1)
📂 modules
  📂 sierra-madre (2)
    📂 pages (3)
      📄 elevation.adoc

1	Defines the component version as wyoming 1.0
2	Defines a module named sierra-madre
3	Defines subsequent files as pages

Using files from Example 15 and Example 16, let’s reference treeline-warning.adoc (target partial) from elevation.adoc (current page). The treeline-warning.adoc partial belongs to the component version colorado 5.2. The elevation.adoc page belongs to the component version wyoming 1.0.

The include directive in Example 17 will embed the content of the treeline-warning.adoc partial into the elevation.adoc page.

Example 17. elevation.adoc (current page)

include::5.2@colorado:ROOT:partial$treeline-warning.adoc[]

As shown in Example 17, the target partial’s version coordinate is 5.2, its component coordinate is colorado, its module coordinate is ROOT, its family coordinate is partial$, and its file coordinate is treeline-warning.adoc. You could also specify the resource ID for treeline-warning.adoc as 5.2@colorado::partial$treeline-warning.adoc (notice the module coordinate ROOT seems to be missing). When the target partial’s component coordinate is specified, and the target partial belongs to the ROOT module, the module coordinate ROOT doesn’t have to be explicitly specified. However, you must still enter the colon (:) that would follow the module coordinate. This shorthand only works when a component coordinate is specified and the module coordinate of the target partial is ROOT.

Use the latest version of a partial

This behavior only applies when the target partial and current page belong to different docs components!

If a version isn’t specified in the resource ID assigned to an include directive, and the target partial and current page don’t belong to the same component, Antora uses the version coordinate of the latest version of the target partial’s component to complete the resource ID at runtime.

Let’s use the files that belong to the component versions colorado 5.2 (Example 18), wyoming 1.0 (Example 19), and wyoming 1.5 (Example 20) as the basis for the example in this section.

Example 18. Directories and files assigned to colorado 5.2

📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pages
      📄 willow-creek.adoc

1	Defines the component version as colorado 5.2

Example 19. Directories and files assigned to wyoming 1.0

📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pages
      📄 elevation.adoc
    📂 partials
      📄 bears.adoc

1	Defines the component version as wyoming 1.0

Example 20. Directories and files assigned to wyoming 1.5

📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 pages
      📄 elevation.adoc
    📂 partials
      📄 bears.adoc

1	Defines the component version as wyoming 1.5

Let’s reference the bears.adoc partial (target partial) from the willow-creek.adoc page (current page). willow-creek.adoc belongs to component version colorado 5.2. There are two files named bears.adoc that belong to the wyoming component, sierra-madre module, and partials family. One bears.adoc belongs to version 1.0, the other bears.adoc to version 1.5.

Example 21 shows an include directive referencing bears.adoc (target partial) from willow-creek.adoc (current page). Notice that the target partial’s version coordinate isn’t specified.

Example 21. willow-creek.adoc (current page)

include::wyoming:sierra-madre:partial$bears.adoc[]

When Antora runs, it will identify wyoming 1.5 as the latest version of the wyoming component according to its version sorting rules and latest version criteria. Because a version coordinate isn’t specified in Example 21, Antora will complete the resource ID assigned to the include directive using the version coordinate — 1.5 — from the latest wyoming component.

This behavior of linking to the latest version only applies when the version coordinate is unspecified and the target partial and current page belong to different components. If the version and component coordinates aren’t specified in the resource ID, Antora assumes the target partial belongs to the same component version as the current page and uses the current page’s version and component coordinates to complete the target partial’s resource ID.

Include directive placement

An include directive is placed at the beginning of a new line. The content from the target partial 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 partial 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 22. current-page.adoc

A paragraph in the page.

include::partial$cli-options.adoc[tag=compass] (1)

A line of content.
include::partial$addendum.adoc[] (2)
Another line of content.

1	To display the included content as a standalone block, make sure there is an empty line above 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.

Include diagram source

If you use diagrams in your pages that are generated from source, you may want to store the diagram’s source in a separate file. It’s up to you whether to store that source as an example or partial. Since the source is not a code example, a partial seems like the more logical place.

Create a folder under the partials directory and name it diagrams. Then, store the source of your diagram in that folder. Let’s assume the file is named partials/diagrams/my-schema.puml. You can now include that source into your page as follows:

Example 23. Include the source of a diagram

[plantuml,my-schema,svg]
....
include::partial$diagrams/my-schema.puml[]
....

You can refer to diagram sources in other modules, versions, or components, just like with other partials.

Learn more

AsciiDoc and Asciidoctor resources