Defining tables in Asciidoctor is very easy. The start and end of the table are defined by
|===. But if we want to add a new table to a table cell we cannot use the same syntax. To define a nested table we must replace the
| separator with
!. So instead of
|=== to indicate the table boundaries we use
!===. Also the cell separators are now
! instead of
|. Finally we must make sure the table cell or column supports Asciidoc markup, so the table is properly created. We must configure the cell or column with
a so the nested table is created.
In the following example Asciidoctor markup we have a simple table with a nested table in the second column and row. Notice we can still apply all table configuration to the nested table as well:
== Nested tables
To nest a table in a table we must
use `!` as table separator instead of `|`.
Also the type of the column or cell
must be set to `a` so Asciidoc markup
| Col 1 | Col 2
| Cell 1.1
| Cell 1.2
| Cell 2.1
| Cell 2.2
! Col1 ! Col2
When we run Asciidoctor to create HTML for this markup we get the following result:
Written with Asciidoctor 1.5.5.
Adding a block title in Asciidoctor is easily done by adding a line at the top of the block that starts with a dot (
.). The text following the dot is then used as the title of the block. But if the text of the title itself starts with a dot (
.) Asciidoctor get’s confused. For example if we want to use a filename that starts with a dot (
.filename) we must use different syntax to set the block title with the filename.
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
Asciidoctor is a Ruby tool, but luckily we can use AsciidoctorJ to use Asciidoctor in Java code. The Asciidoctor Gradle plugin relies on AsciidoctorJ to run. AsciidoctorJ allows us to write custom extensions in Java (or Groovy), but we can still use Asciidoctor extensions written in Ruby with the Gradle plugin.
In Asciidoctor we can add an anchor with an ID to a section or title and then reference it in a link. The title of the section is used as link text. We can alter that when we define the link, but if we rely on the default behaviour we create a title for our section including the caption label and number. This way the created link points to the correct section and the text contains the caption text and number for that section.
Asciidoctor has some built-in attributes to work with captions for certain content blocks. For example the
table-section attribute defines the caption label (by default Table) that is prefixed to a counter for all tables in the document. When we transform our markup Asciidoctor will insert the text Table followed by the table number. By default the caption for listing blocks is disabled, but we can easily enable it with the
In Asciidoctor we can configure syntax highlighting for our source code listings. We can choose from the built-in support for Coderay, Pygments, highlight.js and prettify. The syntax highlighter libraries Coderay and Pygments support extra highlighting of lines, so we can add extra attention to those lines. In this post we see how to use the line highlighting feature in Asciidoctor.
With Asciidoctor we can use images in our documents with the
image directive. When the document is converted each image gets a caption. By default the caption label is Figure followed a number for the position of the image in the document. So the first image has a caption Figure 1.. If we add a block title (text prefixed with a
.) to the image then that text is used in the caption as well. We can customize the caption label, figure counter, caption text or disable the figure caption using a combination of document and
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:
When we use the
include directive to include another document we can must make sure the included document fits the levels of our main document. For example the included document shouldn’t have level 0 headings if the main document already contains a level 0 heading. We can change the level offset in the main document before including another document. This will change the heading levels for the included document so all heading rules are okay.