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:

:name: value

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.

Examples of document attributes

= Page Title
:page-topic-type: concept (1)
:source-language: javascript (2)
:url-downloads: https://www.couchbase.com/downloads (3)
:tabs: (4)

Download Sync Gateway from the {url-downloads}[Couchbase downloads page]. (5)

[source] (6)
----
Snippet of javascript source code
----

1	Attribute names that start with `page-` are specially handled by Antora.
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 `tabs`.
5	Reference an attribute in the body of the document by entering the attribute name inside a set of curly brackets (`{attribute-name}`).
6	Code blocks are assigned the source language `javascript`.

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)

1	Unset `sectids` with a `!` so that sections IDs are not generated from the section titles in the document.

See the production and staging Antora playbooks to review which AsciiDoc attributes are currently set and unset for all of the Couchbase documentation pages.

Using Roles

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 ([.role-name]).

Page Role

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:

tiles
-toc

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 page- prefix. 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:

page-layout

Specifies the UI layout to apply to the page. If not set, the page layout defaults to default (hence loading the default.hbs template).

The home page for the site uses the home layout by assigning :page-layout: home in the document header.

page-partial

Indicates that this page may be included in another page. Only requires for AsciiDoc files in the pages directory (not the partials directory).

page-aliases

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 .adoc filename, for a page in the same module:

:page-aliases: search-query.adoc

Through another module — ROOT:search-query.adoc — to redirecting to a page in another repo:

:page-aliases: 7.0@server:developer-guide:expiry.adoc

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:

page-edition: 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.
page-status: 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.
description: Sets the value of the meta description in the HTML head. Note that the page- prefix is not required in this case.
keywords: 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.