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.
Open a new file in your preferred IDE or plain text editor.
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.
[WARNING] ==== High, open places above the treeline are awe-inspiring-- but you also need to be prepared for the altitude and rapidly changing weather conditions. ====
Once you finish creating your content, save the file with the extension
.adocin 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.
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.
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.
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.
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.