Asciidoctor Extended Syntax Guide

on

The purpose of this article to make sure not-so-common features of Asciidoctor (i.e. admonition blocks, callouts) are styled and fit to the theme. It also serves as a quick introduction to more Asciidoctor as well. Feel free to steal this if you want a template for this.

Admonition blocks

Admonition blocks contain content that are not a part of the main content but you’ll want to draw attention to the audience anyways.

By default, Asciidoctor provides five labels for admonitions:

  • TIP

  • NOTE

  • IMPORTANT

  • CAUTION

  • WARNING

CAUTION vs WARNING

As the user manual has said, CAUTION and WARNING should be used with different semantics.

CAUTION basically advises the user to observe care. WARNING warns the user about the dangers or consequences that’ll exist.

Writing an admonition is intuitively easy, simply write the label in all uppercase and append with a colon. Then write the content after.

TIP: Lorem ipsum dolor sit amet consectetur adipiscing elit varius cursus
orci nulla, fames nisl sodales scelerisque eu consequat sem imperdiet ac mi
vivamus tempor, accumsan ad justo odio viverra praesent senectus class egestas duis.

It’ll render as this:

Tip
 Lorem ipsum dolor sit amet consectetur adipiscing elit varius cursus orci nulla, fames nisl sodales scelerisque eu consequat sem imperdiet ac mi vivamus tempor, accumsan ad justo odio viverra praesent senectus class egestas duis.

In case you want to style the labels differently such as assigning appropriate colors or an icon to the rest of the labels, here’s the rest of them:

Note
 Malesuada mattis aenean ultrices netus cursus viverra vivamus ultricies, velit molestie penatibus phasellus in ante luctus, habitant suspendisse eros turpis taciti risus himenaeos.
Important
 Velit fringilla feugiat nibh id faucibus scelerisque facilisis ac, suscipit quisque odio libero ullamcorper curabitur fames nascetur, elementum tristique hac nisl etiam dictumst dapibus.
Caution
 Tempus dui aptent tempor torquent lacinia sem cursus porta cras semper accumsan feugiat, himenaeos mi ullamcorper pharetra enim class eget auctor conubia metus curabitur.
Warning
 Aliquet ut maecenas mollis id enim nibh suscipit quisque posuere cum fusce, dignissim ad curabitur odio ac diam pharetra platea vivamus eleifend.

Callouts

Callouts are used to add annotations within a verbatim block. This is especially useful for code listings in order to effectively explain what is going on within the code.

Here’s an example of using callouts.

[source,python]
----
from pathlib import Path
from re import compile, match

current_directory = Path(".") <1>
notes_directory = current_directory / "notes/" <2>
----
<1> Created a Path object
<2> Appending a Path object with "/"

And it’ll render as:

from pathlib import Path
from re import compile, match

current_directory = Path(".") # (1)
notes_directory = current_directory / "notes/" # (2)

  1. Created a Path object

  2. Appending a Path object with "/"

One of the most important you should style is the callout number on the code listings block. Normally, when a user wants to copy-paste (even though I don’t personally encourage it), the callout number gets in the way and they have to manually remove them which can be annoying.

Either attach the property user-select with it or take a part from the default Asciidoctor stylesheet and include it in your own stylesheet.