Awesome Asciidoctor: Document Attributes With Styling

Document attributes in Asciidoctor are very powerful. We can assign values to a document attributes and reference the attribute name in our document enclosed between curly braces. Asciidoctor will fill in the value when the document is transformed. Instead of a plain value we can also use styling markup in the document attribute definition. We must use the passthrough macro and allow for quote substitution.

In the following example document we define three document attributes: cl-added, cl-updated and cl-changed. We use the passthrough macro, quotes substation to assign CSS classes:

= Attributes with styles
// Include contents of docinfo.html
// in HTML head with CSS style
// definitions for .label.added,
// .label.changed and .label.updated
// used in the document attributes
// cl-added, cl-changed and cl-updated.
:docinfo1:

// Document attribues with styling,
// using the passthrough macro
// and quotes subsitution.
// We can use quotes or the short-hand q.
:cl-added: pass:quotes[[.label.added]#Added:#]
:cl-changed: pass:q[[.label.changed]#Changed:#]
:cl-updated: pass:q[[.label.updated]#Updated:#]


== Sample section

* {cl-added} Document attributes for document.
* {cl-changed} Definition of attributes to include
 more options.
* {cl-updated} New version of Asciidoctor.

Notice we need a file docinfo.html with the CSS style definitions:

<style>
.label {
    color: #fff;
    padding: .2em .6em .3em;
    font-weight: 700;
    border-radius: .25em;
    font-size: 90%;
}

.added {background-color: #007700;}
.changed {background-color: #088;}
.updated {background-color: #3344bb;}
</style>

When run Asciidoctor to get HTML output we see the following:

Written with Aciidoctor 1.5.7.1.

Awesome Asciidoctor: Changing Values for Default Captions

Asciidoctor has several captions and labels that can be overridden with document attributes. We need to define a document attribute and assign a new value to override a default caption or label. We can use UTF-8 characters as the value. The following list shows captions and labels we can override:

• :appendix-caption:
• :caution-caption:
• :example-caption:
• :figure-caption:
• :important-caption:
• :last-update-label:
• :manname-title:
• :note-caption:
• :table-caption:
• :tip-caption:
• :toc-title:
• :untitled-label:
• :version-label:
• :warning-caption:

In the next example Asciidoctor document we override caution-caption and last-update-label:

= Change default captions

:caution-caption: Watch out!
:last-update-label: I was created on

== Sample

CAUTION: Simple caution message to show changed caption.

We get the following HTML output:

This mechanism can be used to provide messages for other languages than English. The Asciidoctor Github repository contains a file with already translated values for a lot of languages. We include this document in our own Asciidoctor markup and we set the document attribute lang with the value we want, eg. nl. In the following example document we include the file https://raw.githubusercontent.com/asciidoctor/asciidoctor/v1.5.5/data/locale/attributes.adoc.

= Asciidoctor
// Set lang document attribute.
// This attribute is used in the
// included document attributes.adoc.
:lang: nl

// Include translations for built-in captions and labels.
// To make the inclusion with a URI work we must
// run Asciidoctor with attribute allow-uri-read:
// $ asciidoctor -a allow-uri-read sample.adoc
:i18n-labels-uri: https://raw.githubusercontent.com/asciidoctor/asciidoctor/v1.5.5/data/locale
include::{i18n-labels-uri}/attributes.adoc[]

// Simple caution block, where caption
// should be replaced by Dutch text.
CAUTION: Simpel bericht met `lang` document attribuut: {lang}.

// Labels for example blocks are also
// translated.
.Titel
====
Bijvoorbeeld label voor voorbeelden is ook aangepast.
====

When we invoke Asciidoctor via the command line we must add the option -a allow-uri-read to the remote document is included. The following screenshot shows the output:

Written with Asciidoctor 1.5.5.