Asciidoctor Extended Syntax Guide

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)

Created a Path object
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.

Passthroughs

A passthrough passes the input as it is on the final output. This is useful for web-based outputs, for example passing raw HTML for interactive scripts or to create a live result.

Below is a very simple example with a p5.js sketch.

Here is the input from the source code of this document.

++++
<div id="example-sketch"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.0.0/p5.js"></script>
<script>
const sketchuuuuu = ( sketch ) => {
  let x = 100;
  let y = 100;

  sketch.setup = () => {
    sketch.createCanvas(300, 380);
  };

  sketch.draw = () => {
    sketch.background(0);
    sketch.fill(255);
    sketch.rect(x,y,50,50);
    sketch.ellipse(sketch["mouseX"], sketch["mouseY"], 20);
  };
};

let example_sketch = new p5(sketchuuuuu, "example-sketch")
</script>
++++

This is the closest instance of literate programming in the web when using Asciidoctor. (Sadly, not as flexible or cool as Org-Mode or Jupyter Notebooks.)