Attributes and Roles
Setting and Referencing Document Attributes
AsciiDoc attributes are optional key-value pairs that can be used to hold names, URLs, and reusable content phrases. Some attributes are built-in to Asciidoctor; others are defined especially for the Couchbase documentation or by the writer.
When defined in the document header, these attributes become available to the whole document and all of its includes. Each attribute must be entered on a separate line, known as an attribute entry. The syntax of an attribute entry as follows:
In this case,
name is the name of the attribute and
value is the optional value.
You can see several examples of attribute entries in the listing below.
|1||Attribute names that start with
|2||A value can be assigned to a built-in attribute in the document header.|
|3||Writers can set and define their own attributes.|
|4||Some attributes are assigned an implicit value.
In this case, the tabs feature is turned on by setting
|5||Reference an attribute in the body of the document by entering the attribute name inside a set of curly brackets (
|6||Code blocks are assigned the source language
Unsetting a Document Attribute
Some built-in attributes are set (turned on) by default and set for all of the Couchbase document in the playbook.
For example, section IDs are automatically generated for all of the Couchbase documentation pages.
This occurs because the
sectids attribute is turned on by default.
To unset (turn off) an attribute on a page, prefix the name with a bang (
= Page Title :!sectids: (1)
See the production and staging Antora playbooks to review which AsciiDoc attributes are currently set and unset for all of the Couchbase documentation pages.
A role applies alternative or additional CSS styles to a document, block, or phrase.
The styles for each role are defined by the UI.
A role is applied to a block or phrase by prefixing the role name with a dot and inserting it between a set of square brackets (
Assign a role to the page works a little differently.
When set, the
page-role attribute applies one or more roles to the entire page.
page-role is an example of a page attribute.
It must be defined in the document header.
Unlike with blocks and phrases, page roles are not prefixed with a dot and must be separated by a single space (following the same rules as CSS classes).
The Couchbase documentation currently supports two page roles:
These roles are often combined, as you can see in this example:
= Document Title :page-role: tiles -toc Page contents.
You can see the
tiles -toc page role combination in action on the Starter Kits page.
The tiles role arranges the secondary section titles as tiles (in two columns).
The -toc role tells the UI template not to add a table of contents (TOC) to the page.
Using Page Attributes
Certain document attributes are reserved specifically for use with Antora.
These are know as page attributes.
All page attributes begin with the
The prefix is removed and the remainder is passed on to the UI as metadata.
For the most part, it’s up to the UI to decide how to use this information.
There are several built-in page attribute in Antora and a few others that the Couchbase UI already recognized.
Built-in Page Attributes
The built-in page attributes in Antora are as follows:
Specifies the UI layout to apply to the page. If not set, the page layout defaults to
default(hence loading the
The home page for the site uses the
homelayout by assigning
:page-layout: homein the document header.
Indicates that this page may be included in another page. Only requires for AsciiDoc files in the pages directory (not the partials directory).
A comma-separated list of alternate page IDs that should redirect to this page. We recommend that, as far as possible, you avoid renaming or moving pages when editing the documentation. If you do need to move or rename a page, you will need to list the old page ID in this attribute so that the web server will redirect visitors from the old page to the new location.
These can be given as just the
.adocfilename, for a page in the same module:
Through another module —
ROOT:search-query.adoc— to redirecting to a page in another repo:
Note that here the version number must be used to specify which particular page version in the other repo is redirecting to this one.
Antora also assigns several page attributes on each page to provide information about which component, version, and module in which the page is located. You can find a list of these attributes in the Antora documentation.
Custom Page Attributes
Custom page attibutes are used to pass information from the document to the UI. It’s up to the UI to give these attributes meaning.
The Couchbase UI supports the following custom page attributes:
Used to add a blue badge under the page title that indicates the server edition to which the content applies. The badge automatically links to https://www.couchbase.com/products/editions. The value of the attribute is used as the text of the badge.
Used to add an orange badge under the page title that indicates the status of the page, such as beta or the minimum software version to which the content applies. The value of the attribute is used as the text of the badge.
Sets the value of the meta description in the HTML head. Note that the
page-prefix is not required in this case.
Sets the value of the meta keywords in the HTML head. Note that the
page-prefix is not required in this case.
Additional custom page attributes can be added by agreeing on a contract between the page and the UI.