Create a Partial

Unlike a page, a partial doesn’t have any structural requirements other than its content is marked up with valid AsciiDoc. It doesn’t need a title or section headings, though it can contain those elements.

Create and save a partial

  1. Open a new file in your preferred IDE or plain text editor.

  2. On the first line of the file, enter your content, such as paragraph text, a table, or an attribute entry. In this example, let’s create an admonition that’s going to be used on several pages throughout the site.

    High, open places above the treeline are awe-inspiring--
    but you also need to be prepared for the altitude and
    rapidly changing weather conditions.
  3. Once you finish creating your content, save the file with the extension .adoc in a partials directory.

    📂 modules
      📂 ROOT
        📂 pages
          📄 a-source-file.adoc
        📂 partials
          📄 treeline-warning.adoc

You’ve created a partial! Now, it’s ready to be included in a page.

Keep the current page’s context and structure in mind

As you create the content in a partial, there are certain AsciiDoc elements that you may need to adjust according to the current page’s context and structure. A partial is converted after it’s inserted into a page, i.e., the current page. Therefore, the current page’s component version, module, attributes, and other elements are applied to and may impact the included content.

Referencing pages and resources


If the partial is included in pages that belong to other modules or docs components, you’ll need to construct any target page IDs accordingly. The number of coordinates required depends on what component version and module the current page belongs to in relation to the page being referenced by the xref in the partial.

Images, examples, and other partials

A partial can reference other resources. Like when entering page IDs in xrefs, the resource ID of the target resource may need additional coordinates specified depending on what component version and module the current page belongs to in relation to the resource being referenced in the partial.

Section headings

A partial can contain section headings. You may need to use the leveloffset attribute to adjust the partial’s heading levels, depending on where you enter the referencing include directive in a current page.

Inline, block, and section IDs

IDs in a partial can’t conflict with IDs in a current page.


Attributes can be set, assigned, and referenced in a partial. When an attribute is referenced in a partial, either the partial, current page, or current page’s component version descriptor must set and assign a value to the attribute.

If an attribute is set and assigned a value in a partial, the attribute will be available in the current page starting from the point where the partial is included. In such cases, it will override an attribute with the same name that is set/unset in the current page’s header or soft set/unset via the current page’s component version descriptor.