Intrinsic Attributes
Antora automatically assigns information about the runtime environment, site configuration, and current page to various document and page attributes. We refer to these as intrinsic attributes. Antora uses these attributes to propagate information about the site and current page to the AsciiDoc content, extensions, and UI templates.
Unlike other built-in attributes, such as page-aliases, intrinsic attributes are meant to be a conduit to pass information from Antora to the page. Therefore, intrinsic attributes are intended to be read-only and should not be reassigned.
These attributes are defined at the time the page or navigation file is loaded (i.e., parsed). They are not yet assigned when the attributes in the component descriptor are resolved, and are thus not visible to the component descriptor.
Intrinsic environment attributes
Intrinsic environment attributes communicate to the document (or document extension) that the document is being processed by Antora. These attributes are set on every page in the site.
-
env=site -
env-site -
site-gen=antora -
site-gen-antora
You might use these attributes in an preprocessor conditional to include or exclude content based on whether the document is being process by Antora. For example:
ifndef::site-gen-antora[]
include::local-preview-settings.adoc[]
endif::[]You can define additional environment attributes in the playbook.
Site and configuration attributes
Antora sets various attributes to configure the AsciiDoc processor.
-
attribute-missing=warn -
!data-uri -
icons=font -
sectanchors -
source-highlighter=highlight.js
These attributes are intended to be reasonable defaults. Unlike other intrinsic attributes, they can be reconfigured using the CLI or playbook. They can also be redefined in such a way that they can be overridden by the component descriptor or page.
The only syntax highlighter that Antora currently supports for source blocks is highlight.js.
Therefore, it doesn’t make sense to change the source-highlighter attribute to any other value.
If you’d like to disable syntax highlighting on source blocks, you can disable this attribute.
|
Antora also passes general site information using attributes.
-
site-title -
site-url
The values of these attributes match the values defined in the playbook.
Intrinsic page attributes
Antora passes various information about the current page through page attributes. These attributes are reassigned for each page as well as each navigation file.
| Attribute | Description | Example Output |
|---|---|---|
|
The display version of the component version as specified in antora.yml. |
7.1 Beta |
|
The component name of the component version as specified in antora.yml. |
silver-leaf |
|
The component title of the component version as specified in antora.yml. |
Silver Leaf |
|
The version string of the latest version in the component for the current page. |
7.5 |
|
The version of the component version as specified in antora.yml. |
7.1 |
|
Set if the component version for the current page is the latest version in the component for the current page. |
empty |
|
The URL where the page’s source file can be edited. |
https://gitlab.com/forest-co/silver-leaf/edit/main/modules/ROOT/pages/index.adoc |
|
ROOT |
|
|
The name of the repository branch where the page’s source file is stored. (mutually exclusive with |
v7.1.0 |
|
Set if the origin where the page’s source file is stored is private. |
empty |
|
The SHA-1 hash of the reference where the page’s source file is stored.
If the file was taken from a git worktree (i.e., local directory), the value is |
e8e6f6ba33b1ab3f796907b5a256893a64844cd1 |
|
The name of the reference where the page’s source file is stored. |
v7.1.0 |
|
The reference type (e.g., tag or branch) where the page’s source file is stored.
If the file was taken from a git worktree (i.e., local directory), the value is |
branch |
|
The name of the repository tag where the page’s source file is stored. (mutually exclusive with |
v7.1.0 |
|
The start path of the content source where the page’s source file is stored. |
docs |
|
The type (e.g., git) of content source where the page’s source file is stored. |
git |
|
The URL, without credentials, of the content source where the page’s source file is stored. |
https://gitlab.com/forest-co/silver-leaf.git |
|
The absolute path of the git worktree (i.e., local directory). Only set if the file was taken from a git worktree. |
/user/projects/project-name |
|
The family-relative path of the page’s source file (starting from modules/<module>/pages). |
whats-new-in-spiky.adoc |
|
Alias for |
7.1 |
Keep in mind that the AsciiDoc processor also assigns numerous intrinsic attributes to communicate information about the current document (e.g., docname and docfilesuffix), though these are not page attributes (meaning they are not prefixed with page-).
Put intrinsic page attributes to work
The value of these page attributes can be accessed in the AsciiDoc content using the attribute reference syntax (e.g., {page-component-name}) or via the page UI model using a template variable (e.g., page.attributes.component-name).
This page belongs to the *{page-module}* module in the *{page-component-title} {page-component-version}* component version.
The attribute references in the above example output the data (shown below) for the current page, that is, the page you’re reading right now.
This page belongs to the page module in the Antora 3.1 component version.
Since these are page attributes, they are promoted to the page.attributes map in the page UI model with all other page attributes.
They can be accessed in a UI template using a property expression (e.g., page.attributes.component-name).
To learn more about how page attributes work, see Page Attributes.