To write a (nested) ordered lists in Asciidoctor is easy. We need to start the line with a dot (
.) followed by a space and the list item text. The number of dots reflects the levels of nesting. So with two dots (
..) we have a nested list item. By default each nested level has a separate numbering style. The first level has arabic numbering, the second lower case alphanumeric, the third upper case alphanumeric, the fourth lower case roman and the fifth (which is maximum depth of nested levels in Asciidoctor) has style upper case roman. But we can change this by setting a block style for each nested level block. The name of the block style is
upperroman. With the HTML5 backend we can also use
In our Asciidoc markup we can include delimited blocks, like sidebars, examples, listings and admonitions. A delimited block is indicated by a balanced pair of delimiter characters. For example a sidebar starts and ends with four asterisk characters (
****). If we want to nest another delimited block of the same type we must add an extra delimiter character at the start and end of the nested block. So when we want to nest another sidebar block inside an existing sidebar block we must use five asterisk characters (
When we transform our Asciidoc source files to HTML Asciidoctor will print the date and time the document was last updated in the footer. If we want to disable the Last updated text we disable the document attribute
Normally all Asciidoc files are processed and transformed to output files by Asciidoctor. But if we start the file name with an underscore (
_) the file is not transformed to an output file. This is very useful, because we can define some Asciidoc document fragments and include them in other Asciidoc files, but in the output directory the document fragment is not generated.
We can change the frames and grid of tables we define in Asciidoctor. We use the
frames attribute to change the outside frame of a table. We can choose between
topbot for top and bottom,
sides for only a frame at the sides of the table,
none if we don’t want a frame. The default value
all create a frame around our table with top, sides and bottom.
To change the inner grid of a table we use the
grids table attribute. The default value
all displays a grid for columns and rows inside the table. The value
cols only displays a grid between columns, value
rows display a grid between rows and with value
none there will be no grid inside our table.
With Asciidoctor we can create tables where the header and rows are in CSV (Comma Separated Values) and DSV (Delimiter Separated Values) format. Normally we use a pipe-symbol (
|) to separate cell values. This is actually PSV (Prefix Separated Values) :-).
In a previous blog post we learned about the conditional directives in Asciidoctor. Dan Allen mentioned a conditional directive that we can use to see if the document is used on GitHub. The conditional directive is called
To use font icons from FontAwesome we set the document attribute
icons with the value
font. The default link to the CSS location is
https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.1.0/css/font-awesome.min.css. We can change the location for the FontAwesome CSS with document attributes.
When we define the document attribute
icons with the value
font the FontAwesome fonts are loaded in the generated HTML page. In the
head section of the HTML document a
link element to the FontAwesome CSS on
cdnjs.cloudflare.com server is generated. We can change the value of the scheme from
http by setting the attribute
cdnjs.cloudflare.com server. Remember this might provide a problem if the HTML page is opened locally.
When we write technical documentation with Asciidoctor we can easily include source code listings. When we use the
pygments source code highlighter we can also include line numbers. We must add the attribute
linenums to the listing block in our markup. This attribute is used by the source highlighters to create and format the line numbers. We can specify that the line numbers must be generated in table mode or inline mode. When the line numbers are in table mode we can select the source code without the line numbers and copy it to the clipboard. If we use
inline mode the line numbers are selectable and are copied together with the selected source code to the clipboard. To specify which mode we want to use for the line numbers we use the document attribute
pygments-linenums-mode depending on the source highlighter we use. We can use the values
table (default) or