Antora 101: Avoid Duplicate Content With Page and Site Attributes

While writing technical documentation is not the same as writing software code, there are ways in which the two do overlap. For example, when writing code you can often find that you have written the same, or reasonably similar, functionality in several places.

At times like these, one of the best things you can do is to refactor the code into a variable, function, or class, so that it can be reused, and the duplication removed. Taking the time to do so reduces both maintenance overhead and the likelihood of errors, and is so common and accepted that it’s not worth debating.

However, this paradigm exists in technical writing as well. For example, take the following code snippet which exists within the ownCloud documentation:

[source,console]
----
FILE="/usr/local/bin/occ"
/bin/cat <<EOM >$FILE
#! /bin/bash

cd /var/www/html/ownCloud
sudo -u www-data /usr/bin/php /var/www/html/ownCloud/occ "\$@"
EOM
----

You can see that the script does two things:

1. It cd’s into the ownCloud installation directory (/var/www/html/ownCloud)
2. It runs a PHP script, located inside the ownCloud installation directory, as the web server user (www-data).

In this script, the ownCloud installation directory path is written twice. If this were code, would you write the string twice? Or would you store the string in a variable, and use the variable in both locations?

Admittedly, this is a rather small and trivial example; but consider if the path was used five or more times, or if a number of other variables were duplicated as well.

Now, let’s assume that we have a number of subsequent code examples on the same page in the documentation where this example was taken from, anywhere in the order of 10 or more. To write the directory name in each one of them doesn’t make sense as:

1. For some, as yet undefined, reason we may want to change that example directory path at a future point in time. At this point, someone will need to perform a find/replace (potentially requiring a regular expression) to update each reference.
2. What if the path was different in a handful of places? How much confusion would this cause the reader as they were working through the examples? How frustrating would this be for the maintainers to track down and correct.

As these two reasons show, copying and pasting a string, such as this, might seem quick and easy—even efficient—at the time, but the reality is that it’s creating a lot of unnecessary work for the future. The more it happens, the higher the maintenance overhead, and cost, will be for your documentation.

It doesn’t have to be this way though, as AsciiDoc, around which Antora is based supports attributes. AsciiDoc attributes are analogous to variables in software. They can, among other things, store content.

By using them, you can store the directory path once and reuse it throughout each code example in the page. Have a look below at the revised version of the earlier code example, to get a feel for how we would use them.

[source,console,subs="attributes+"]
----
:owncloud-installation-path: /var/www/html/ownCloud

FILE="/usr/local/bin/occ"
/bin/cat <<EOM >$FILE
#! /bin/bash

cd {owncloud-installation-path}
sudo -u www-data /usr/bin/php {owncloud-installation-path}/occ "\$@"
EOM
----

At the top of the example, we define an attribute called owncloud-installation-path, and set it’s value to /var/www/html/ownCloud. We then use the attribute in place of the literal string.

Before we go too much further, several things are worth knowing about attributes—especially when using them in Antora.

Attribute Naming Rules

Quoting the AsciiDoc manual, they:

• Must be at least one character long,
• Must begin with a word character (A-Z, a-z, 0-9 or _) and
• Must only contain word characters and hyphens.

Attribute Value Rules

The attribute value:

• Can be any inline content; and
• Can only contain line breaks if an explicit line continuation character is used.

Take Care With Attributes Inside Code Blocks

In the code block header, ,subs="attributes+" was required to be added at the end of the definition. This is necessary for code blocks because code blocks are rendered without any substitution being performed. As a result, the attribute would not be interpolated when Antora builds the documentation, so you would see the code example literally as it is written above, instead of with the installation directory path values.

Antora Has Predefined Page and Site Attributes

If you check out Antora’s page and site attributes documentation, you’ll see that it has fourteen predefined page attributes and four predefined site attributes. Be careful that you don’t abuse them (ideally, make best use of them).

Site Attributes

Now, page-level attributes are fine for use on a single page. But in some cases, and the previous example is a good one, an attribute may be applicable to multiple pages within either a documentation project. In these cases, you can make use of Antora’s site attributes.

Site attributes are defined a little differently to page attributes, but otherwise work the same way. The code sample below shows a small example of how they’re defined.

asciidoc:
  attributes:
    std-port-http: 8080
    std-port-memcache: 11211
    std-port-mysql: 3306
    std-port-redis: 6379
    owncloud-installation-path: '/var/www/html/ownCloud'

Site attributes are defined in site.yml, under the asciidoc.attributes key. In the code sample above, you can see that five attributes have been defined; std-port-http, std-port-memcache, std-port-mysql, std-port-redis, and owncloud-installation-path.

Each one is defined on a new line. Each of these is available for use on any page within an Antora project, as we saw in the earlier example. Other than being defined in a different location, there’s not much else to them.

And That’s a Wrap

While not too lengthy, in this post, we’ve seen how to use attributes in AsciiDoc and Antora to make content within a site reusable, whether that’s on one single page, or on any page within an Antora documentation site.

If this is your first time hearing about attributes, I appreciate that they may take a little bit of time to get used to, if for no other reason than to know where to find the attribute definitions.

For that reason, they may seem like overkill at first. But, the larger your project grows and the more contributors it gains, I’m more than confident it will benefit from reusing content by making use of attributes, instead of being littered with duplicate content.

I strongly encourage you to experiment with attributes and see what you can store in them.

Further Reading

• AsciiDoc Attributes