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:
Continue reading →
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.
In the next Ascciidoc markup sample we use different ways to set the block title for a code block with a filename that starts with a dot.
First we use the title attribute for the block.
Another solution is to use the Unicode value for the dot.
Next we enclose the filename in back ticks ( ` ) which also formats the filename with a monotype font.
And finally we can define the filename via a document attribute and reference the document attribute in the block title:
Continue reading →
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 the following example we use the emoji-inline-macro from Asciidoctor extensions lab.
This is an extension written in Ruby. We create a new directory for our sample and create a lib folder.
Inside the lib directory we copy the file emoji-inline-macro.rb and the supporting directory emoji-inline-macro.
These files are all in the Asciidoctor extensions lab repository.
After we have copied the files we should have the following structure:
Continue reading →
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.
In the following example markup we can see how we can use the caption label and section counter as attributes in the title.
We do this with the title attribute of a section.
By using the single quotes we tell Asciidoctor to interpret the attributes.
We must also make sure we set the caption attribute to an empty string value.
This disables the default caption creation of Asciidoctor for our section.
Finally we need to provide an ID for the section using the #ID syntax:
Continue reading →
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 listing-caption attribute.
In the following markup we enable the caption for listing blocks and set the value to Listing.
This will add the text Listing followed by the listing section counter to the output.
Continue reading →
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.
First we must add the document attribute source-highlighter and use the value coderay or pygments.
When we use Coderay we must also enable the line numbers for the source code listing, because Coderay will highlight the line numbers in the output.
Pygments highlight the whole line, with or without line numbers in the output.
Therefore we choose Pygments in our example.
To highlight certain lines in the source code output we use the highlight attribute for the source code block.
We can specify single line numbers separated by a comma (,) or semi colon (;).
If we use a comma we must enclose the value of the highlight attribute in quotes.
To define a range of line numbers we can define the start and end line numbers with a hyphen in between (eg. 5-10 to highlight lines 5 to 10).
To unhighlight a line we must prefix it with a exclamation mark (!).
For example the following value for the highlight attribute highlights the lines 2, 3 to 7 and not 5: [source,highlight=1;3-7;!5].
Continue reading →
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 image attributes.
We have the following Asciidoctor markup.
We include several images and customize the figure caption settings.
To change the caption label (Figure) we set a different value for the document attribute figure-caption.
In our example we use the value Logo. Any captions following this definition will have the label Logo.
Continue reading →
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:
:appendix-caption::caution-caption::example-caption::figure-caption::important-caption::last-update-label::manname-title::note-caption::table-caption::tip-caption::toc-title::untitled-label::version-label::warning-caption:
Continue reading →
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.
To change the level offset we use the document attribute leveloffset.
It is best to use a relative value, so if the included document also contains included document the output will still be okay and the heading rules still apply.
Alternatively we can use the leveloffset attribute for the include directive.
In the following sample document we include other files with a level 0 heading:
Continue reading →
Asciidoctor has built-in support for a couple of source syntax highlighting libraries like Coderay, Pygments, highlight.js and prettify.
In this post we learn how to use the Javascript library Prism to do the syntax highlighting for our source blocks.
Because Prism is a Javascript library we must remember this only works for the HTML backend of Asciidoctor.
In the following markup we have two source code listings in Java and Groovy:
Continue reading →
In Asciidoctor we can create a document attribute as a counter attribute.
The attribute is automatically incremented each time we use it in our markup.
We can choose to use numbers or characters.
Only latin characters from 'a' to 'z' or 'A' to 'Z' are allowed.
By default the counter will start at 1, but we can define another start value when we use the counter attribute for the first time.
To define a counter attribute we must prefix the attribute name with counter:.
Each time we use this syntax with the counter: prefix the value is incremented and displayed.
To only display the current value, without incrementing, we simply refer to the document attribute without the counter: prefix.
For example if we want to add a counter attribute with the name steps we would use the following markup in Asciidoctor: {counter:steps}.
Continue reading →
With Asciidoctor we can use text to describe a symbol in our markup.
The text is automatically transformed to a Unicode replacement.
For example if we use the text (C) it is converted to © which is the copyright symbol: ©.
In the following sample we see all the symbol replacements:
Continue reading →
