AsciiDoc Format Style Guide

To write effectively in AsciiDoc, you cannot go wrong following the advice of Asciidoctor lead developer Dan Allen and lead writer Sarah White. Four documents by them in particular are essential to fully appreciating what AsciiDoc has to offer.

The rest of this AsciiDoc Format Style Guide is supplementary and complementary to those works.

Use the optional link: prefix for external URLs. This is especially important when the URL is an attribute, so syntax highlighters will identify the components.

Name attributes using lowercase letters, hyphens, and underscores.

Use hyphens to break up words or abbreviations that collectively constitute a label.

Use underscores to delineate parts of the variable name, such as by prepending url_ or appending _uri or xref_.

For instance, in {xref_some-topic-slug}, the underscore designates xref to be a type flag, and the remainder matches a slug. The attribute is the cross-reference code for a file with the slug some-topic-slug.

Similarly, consider {platform-backend_source_git} and {platform-backend_source_www}. These attributes designate a subject (the platform backend), the type of resource being linked (the source code for said subject product) and a designator for which version (the Git repo itself or the web UI frontend).