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.

AsciiDoc include directive

Example 1 shows the structure of an include directive with a partial’s fully qualified resource ID.

Example 1. Include directive and resource ID syntax
include::version@component:module:partial$partial-filename.adoc[]

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

The steps below assume that the target partial and current page belong to the same component version and module, so only the partial$ and resource coordinates of the target partial resource are entered in the resource ID.

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

    include::
  2. Enter the resource ID of the target partial file. When including a page (i.e., a file in the page family), the family segment is optional. In all other cases, the resource ID must specify the partial$ family coordinate since the include directive assumes the family is “page” if not specified.

    include::partial$partial-filename.adoc
  3. Close the directive with a set of square brackets ([]).

    include::partial$partial-filename.adoc[]
  4. The brackets can contain an optional list of attributes. The attributes are entered as key-value pairs separated by commas.

    include::partial$partial-filename.adoc[attribute,attribute]

Include directive placement

A paragraph in the standard page.

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

Another paragraph in the standard page.
include::partial$addendum.adoc[] (2)
1 Enter the include on a new line. If you want the partial contents to be a standalone block, make sure there’s a blank line above and below it.
2 To attach the partial to another block, enter it on a new line but don’t insert a blank line between the include and the block content.

Include a partial from another module

When the target partial file and the current page belong to different modules of the same component version, enter the partial’s module, family (partial$), and resource coordinates in the resource ID.

Example 2. current-page.adoc
include::ROOT:partial$defs.adoc[]

Include a partial from another component

When the target partial file and the current page belong to different docs components, enter the partial’s version, component, module, family (partial$), and resource coordinates in the resource ID.

Example 3. current-page.adoc
include::2.0@catalog::partial$defs.adoc[]

Don’t specify the version coordinate if you want a page to always reference the latest version of the partial.

Example 4. current-page.adoc
include::catalog::partial$defs.adoc[]