Awesome Asciidoctor: Image As Link Reference

To make an image linkable in Asciidoctor when formatted to HTML we must use the link attribute when we use the image macro. The value of the link attribute is the address where the user goes when clicking on the image. We can also specify extra link attributes like window to specify the target window for the link to open in.

In the following example we use the link attribute for a block and inline image, with and without an extra window attribute:

= Image with link

== Simple link

Using the `link` attribute with `image:`

image::haki-logo.png[link="https://www.mrhaki.com"]
A block image.

image:haki-logo.png[link="https://www.mrhaki.com"]
As inline image.

== Link attributes

Set link attribute `window="_blank"` to open link in new browser window:

image::haki-logo.png[link="https://www.mrhaki.com",window="_blank"]

When we transform this markup to HTML we get the following HTML for the images:

...
<div class="paragraph">
<p>Using the <code>link</code> attribute with <code>image:</code></p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="https://www.mrhaki.com"><img src="./images/haki-logo.png" alt="haki logo"></a>
</div>
</div>
<div class="paragraph">
<p>A block image.</p>
</div>
<div class="paragraph">
<p><span class="image"><a class="image" href="https://www.mrhaki.com"><img src="./images/haki-logo.png" alt="haki logo"></a></span>
As inline image.</p>
</div>
</div>
...
<div class="imageblock logo">
<div class="content">
<a class="image" href="https://www.mrhaki.com" target="_blank" rel="noopener"><img src="./images/haki-logo.png" alt="haki logo"></a>
</div>
...

Written with Asciidoctor 2.0.9.

Awesome Asciidoctor: Auto Number Callouts

In a previous post we learned about callouts in Asciidoctor to add explanation to source code. While surfing the Internet I came upon the following blog post by Alex Soto: Auto-numbered Callouts in Asciidoctor. I turns out that since Asciidoctor 1.5.8 we can use a dot (.) instead of explicit numbers to have automatic increasing numbering for the callouts.

Let's take our example from the earlier blog post and now use auto numbered callouts:

= Callout sample
:source-highlighter: prettify
:icons: font

[source,groovy]
----
package com.mrhaki.adoc

class Sample {
    String username // <.>

    String toString() {
        "${username?.toUpperCase() ?: 'not-defined'}" // <.>
    }
}
----
<.> Simple property definition where Groovy will generate the `setUsername` and `getUsername` methods.
<.> Return username in upper case if set, otherwise return `not-defined`.

When we convert this markup to HTML we get the following result:

This makes it very easy to add new callouts without having to change all numbers we first typed by hand.

Written with Asciidoctor 2.0.9

Awesome Asciidoctor: Include Asciidoc Markup With Listing or Literal Blocks Inside Listing or Literal Block

If we want to include Asciidoc markup as source language and show the markup without transforming it we can use a listing or literal block. For example we are using Asciidoc markup to write a document about Asciidoctor and want to include some Asciidoc markup examples. If the markup contains sections like a listing or literal block and it is enclosed in a listing or literal block, the tranformation goes wrong. Because the beginning of the included listing or literal block is seen as the ending of the enclosing listing or literal block. Let's see what goes wrong with an example where we have the following Asciidoc markup:

In the following example we see a listing block that can be defined in Asciidoc markup.

[source,asciidoc]
----
= Sample document

We can include listing blocks which are ideal for including source code.

.A listing block
----
public class Sample { }
----

.A literal block
....
public class Sample { }
....

Asciidoctor awesomeness!
----

When we transform this to HTML we get the following output:

We can use nested listing or literal blocks where we have to add an extra hyphen or dot to the nested block, but then the Asciidoc markup we want to show as an example is not correct anymore. It turns out we can also add an extra hyphen or dot to the enclosing listing or literal block to transform our markup correctly. So in our example we add an extra hyphen to the outer listing block:

In the following example we see a listing block that can be defined in Asciidoc markup.

[source,asciidoc]
// This time we have 5 hyphens.
-----
= Sample document

We can include listing blocks which are ideal for including source code.

.A listing block
----
public class Sample { }
----

.A literal block
....
public class Sample { }
....

Asciidoctor awesomeness!
-----

The transformed HTML looks like this:

If our sample markup we want to show only contains a listing block we could have enclosed it in a literal block to get the same result or sample markup of a literal block could be in a listing block.
But in our example we have both a listing and literal block so we needed another solution to get the desired result.

Written with Asciidoctor 2.0.9.

Awesome Asciidoctor: Don't Wrap Lines in All Listing or Literal Blocks of Document

In a previous post we learned about setting the value of options attribute to nowrap on listing and literal blocks, so the lines in the block are not wrapped. In the comments a user suggested another option to disable line wrapping for all listing and literal blocks in the document by using the document attribute prewrap. We must negate the document attribute, :prewrap!:, to disable all wrapping. If we place this document attribute at the top of our Asciidoctor document it is applied for the whole document. We can also place it at other places in the document to change the setting for all listing and literal blocks following the prewrap document attribute. To enable wrapping again we set :prewrap: (leaving out the exclamation mark).

In the following example we have markup with a listing, literal and example block and we use the document attribute :prewrap!: to disable the wrapping for the listing and literal blocks:

= Wrapping lines sample

// Disable wrapping in listing and literal blocks.
:prewrap!:

== Listing

[.groovy]
----
class GroovyHelloWorld {
    String sayHello(final String message = 'world') { // Set default argument value for message argument
        "Hello $message !"
     }
}
----

== Literal

....
class GroovyHelloWorld {
    String sayHello(final String message = 'world') { // Set default argument value for message argument
        "Hello $message !"
     }
}
....

== Example

====
// We use spacing to mimic a code block.
class GroovyHelloWorld { +
{nbsp}{nbsp}{nbsp}{nbsp}String sayHello(final String message = 'world') { // Set default argument value for message argument +
{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp}"Hello $message !" +
{nbsp}{nbsp}{nbsp}{nbsp}} +
}
====

When we create HTML from this markup we get the following output:

The code in the listing and literal blocks is now not wrapped, but continues on the same line.

Written with Asciidoctor 2.0.2.

Awesome Asciidoctor: Collapsible Content

Since Asciidoctor 2.0.0 we can add the collapsible option to an example block. When the markup is generated to HTML we get a HTML details and summary section. The content of the example block is collapsed (default behaviour because it is in a details section) and a clickable text is available to open the collapsed block (the summary section), so we can see the actual content. The text we can click on is by default Details, but we can change that by setting the title of the example block. Then the title is used as the text to click on to open the collapsed content.

The following example markup has two collapsible blocks with and without a title:

= Sample
:nofooter:
:source-highlighter: highlightjs

== Collapse

[%collapsible]
====
Example block turns into collapsible summary/details.
====

== Exercise

. Implement the `Application` class with `main(String[] args)` method.

=== Solution

// The title attribute is used as
// clickable text to open the example block.
.Click to see solution
[%collapsible]
====
[,java]
----
package mrhaki;

import io.micronaut.runtime.Micronaut;

public class Application {

    public static void main(String[] args) {
        Micronaut.run(Application.class);
    }
}
----
====

When we generate this markup to HTML we get the following result:

And when we expand the collapsible content we see:

Written with Asciidoctor 2.0.2.

Awesome Asciidoctor: Change Striping In Tables

Creating tables with Asciidoctor is easy. When we convert our Asciidoc markup to HTML the rows of the body of the table are striped. The even rows have a slightly darker background color and the odd rows don't have a background color. We can change how the body rows are striped using the table attribute stripes. We can use the values even, odd, all or none. Instead of using the table attribute stripes we can also set the role on the table. The prefix of the role name is stripes- followed by the same values as we can use with the attribute stripes.

In the following example markup we define four table with different striping:

= Tables
:nofooter:

.No striping
// Alternative to stripes attributes is
// setting role "stripes-none" as [.stripes-none,cols="1,2"].
[stripes=none,cols="1,2"]
|===
| Name | Description

| Asciidoctor
| *Awesome* way to write documentation

| Micronaut
| Low resource usage and fast startup micro services
|===

.All rows
// Alternative to stripes attributes is
// setting role "stripes-all" as [.stripes-all,cols="1,2"].
[stripes=all,cols="1,2"]
|===
| Name | Description

| Asciidoctor
| *Awesome* way to write documentation

| Micronaut
| Low resource usage and fast startup micro services
|===

.Odd rows
// Alternative to stripes attributes is
// setting role "stripes-odd" as [.stripes-odd,cols="1,2"].
[stripes=odd,cols="1,2"]
|===
| Name | Description

| Asciidoctor
| *Awesome* way to write documentation

| Micronaut
| Low resource usage and fast startup micro services
|===

.Even rows (default)
// Alternative to stripes attributes is
// setting role "stripes-even" as [.stripes-even,cols="1,2"].
[stripes=even,cols="1,2"]
|===
| Name | Description

| Asciidoctor
| *Awesome* way to write documentation

| Micronaut
| Low resource usage and fast startup micro services
|===

When we convert this markup to HTML we get the following result:

Written with Asciidoctor 2.0.2.

Awesome Asciidoctor: Help On Syntax As HTML

With the release of Asciidoctor 2.0.0 we get nice help on the basic syntax of Asciidoc with the command-line option --help syntax. This gives us samples of the syntax in Asciidoc markup. As mentioned by Dan Allen on Twitter we can pipe the syntax sample to Asciidoctor itself to get a HTML page:

The best part is, it's valid AsciiDoc. So you can pipe it back to the asciidoctor command to convert it:

asciidoctor --help syntax | asciidoctor -o syntax.html -

It offers a nice overview of the language and what it can do. Thanks to @Mogztter for his help on this feature!

— Dan Allen ✊ (@mojavelinux) March 22, 2019

This is very useful! We have the source and the output of Asciidoc markup with really useful samples.

Let's run Asciidoctor with --help syntax and convert it to HTML and open the HTML in our web browser: $ asciidoctor --help syntax | asciidoctor -o syntax.html - && open syntax.html.
We get the following result:

To get the syntax in a Asciidoc markup file we can run $ asciidoctor --help syntax > syntax.adoc.

Written with Asciidoctor 2.0.2.

Awesome Asciidoctor: Exclude Parts From Included Files

In a previous post we learned how to include parts of a document in the generated output. The included parts are defined using tags. The start of a tag is defined in a comment with the format tag::tagName[] and the end has the format end::tagName[]. Next we must use the tags attribute for the include macro followed by the tagName. If we don't want to include a tag we must prefix it with an exclamation mark (!).

Suppose we have an external Java source we want to include in our Asciidoctor document.

package mrhaki;

// tag::singletonAnnotation[]
@Singleton
// end::singletonAnnotation[]
public class Sample {
    public String greeting() {
        return "Hello Asciidoctor";
    }
}

In the following sample Asciidoctor document we include Sample.java, but we don't want to include the text enclosed with the singletonAnnotation tag. So we use tags=!singletonAnnotaion with the include macro:

= Sample

To NOT include sections enclosed with tags we must use `tags=!<tagName>` in the `include` directive.

[source,java]
----
include::Sample.java[tags=!singletonAnnotation]
----

When we transform our Asciidoctor markup to HTML we get the following result:

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Document Attributes With Styling

Document attributes in Asciidoctor are very powerful. We can assign values to a document attributes and reference the attribute name in our document enclosed between curly braces. Asciidoctor will fill in the value when the document is transformed. Instead of a plain value we can also use styling markup in the document attribute definition. We must use the passthrough macro and allow for quote substitution.

In the following example document we define three document attributes: cl-added, cl-updated and cl-changed. We use the passthrough macro, quotes substation to assign CSS classes:

= Attributes with styles
// Include contents of docinfo.html
// in HTML head with CSS style
// definitions for .label.added,
// .label.changed and .label.updated
// used in the document attributes
// cl-added, cl-changed and cl-updated.
:docinfo1:

// Document attribues with styling,
// using the passthrough macro
// and quotes subsitution.
// We can use quotes or the short-hand q.
:cl-added: pass:quotes[[.label.added]#Added:#]
:cl-changed: pass:q[[.label.changed]#Changed:#]
:cl-updated: pass:q[[.label.updated]#Updated:#]


== Sample section

* {cl-added} Document attributes for document.
* {cl-changed} Definition of attributes to include
 more options.
* {cl-updated} New version of Asciidoctor.

Notice we need a file docinfo.html with the CSS style definitions:

<style>
.label {
    color: #fff;
    padding: .2em .6em .3em;
    font-weight: 700;
    border-radius: .25em;
    font-size: 90%;
}

.added {background-color: #007700;}
.changed {background-color: #088;}
.updated {background-color: #3344bb;}
</style>

When run Asciidoctor to get HTML output we see the following:

Written with Aciidoctor 1.5.7.1.

Awesome Asciidoctor: Use Diagram Block Macro To Include Diagrams

With the Asciidoctor diagram extension we can include diagrams that are written in plain text. For example PlantUML or Ditaa diagrams. The extension offers a block processor where we include the diagram definitions in our Asciidoctor document. But there is also a block macro processor. With the block macro processor we can refer to an external file. The file is processed and the resulting image is in our output document.

In the following example we see how to use the block macro for a Ditaa diagram:

= Diagram Block Macro

There is another way to use the diagram
extension instead of via a block definition. We
can use a block macro to refer to an external
file that has the diagram definition.

The name of the diagram extension is the
block macro name. For example for a Ditaa diagram
we use `ditaa::` and for PlantUML
we use `plantuml::`. This is followed
by a filename of the file that contains the
diagram source.

We can define attributes just like with the
block definition. The first positional attribute
define the filename. Or we use the attribute
name `target` to set the output filename. The second
positional attribute is the file format. Instead
we can use the attribute `format`.

In the next example we use a block macro
to include a Ditaa diagram definition:

// The first positional attribute is the
// file target name (or we use attribute target),
// the second positional attribute is the
// file format (or use attribute format).
// Other attributes can also be defined.
ditaa::sample.ditaa[ditaa-diagram, png, round-corners="true"]

Written with Asciidoctor {asciidoctor-version}.

The contents of sample.ditaa:

+-------------+
| Asciidoctor |-------+
|   diagram   |       |
+-------------+       | PNG out
    ^                 |
    | ditaa in        |
    |                 v
+--------+   +--------+----+    /---------------\
|        |---+ Asciidoctor +--->|               |
|  Text  |   +-------------+    |   Beautiful   |
|Document|   |   !magic!   |    |    Output     |
|     {d}|   |             |    |               |
+---+----+   +-------------+    \---------------/
    :                                   ^
    |          Lots of work             |
    +-----------------------------------+

When we create a HTML document from this Asciidoctor markup we get the following output:

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Use Only Block As List Item

When we define a list in Asciidoctor we usually have a list item that is a paragraph. But if we want to have a block as list item we need to add an extra {blank} element to make sure the block is parsed correctly as list item. Because a list item starts with a . or a * at the beginning of a line and a block also is defined on the beginning of the line, we must add the extra {blank} element. Together with the list item continuation (+) we can have a list with blocks.

In the following example we define a numbered list with three listing blocks:

= Simple steps

We need to type the following commands to generated a HTML version
of our Asciidoctor source document:

. {blank}
+
----
$ asciidoctor sample.adoc
$
----
. {blank}
+
----
$ ls
sample.adoc      sample.html
$
----
. {blank}
+
----
$ open sample.html
$
----

When we generate a HTML version we get the following result:

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Prevent Transformation of URL to Hyperlink

Normally if we type an URL in Asciidoctor that starts with a scheme Asciidoctor knows about, the URL is turned into a hyperlink. The following schemes are recognized by Asciidoctor:

• http
• https
• ftp
• irc
• mailto
• email@email.com

If we want to keep our URL as text and not a link we must prepend our URL with a backslash (\). This way Asciidoctor will not transform the URL to a hyperlink in our output.

In the following example we have URL that is transformed to a link, followed by the same URL but with a backslash (\) before it, that is not transformed:

== URL not as a link

The URL http://www.asciidoctor.org  should
be turned into a hyperlink.

But now the URL \http://www.asciidoctor.org should
just be text and not a hyperlink.

If we transform our document to HTML with Asciidoctor we get the following result:

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Using Tab Separated Data In A Table

In a previous post we learned how to use data in CSV and DSV format. Recently we can also include tab separated values (TSV) in a Asciidoctor table. We must set the table attribute format to the value tsv. The data can be inside the document, but also defined in an external file which we add with the include macro.

In the following example markup we have a table with inline tab separated values. A second table includes an external file with tab delimited values:

= Tables

Using the `format` attribute value `tsv` we can
use tab-delimited data for table data.

== TSV table

[format=tsv, options="header"]
|===
Writing tools Awesomeness
Asciidoctor Oh yeah!
MS Word  No!
|===

== Table with external data

// We have an external file with 
// tab-delimited values.

[%header,format=tsv]
|===
include::tools.tsv[]
|===

When we convert our Asciidoctor markup to HTML we get the following result:

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Grouping Floating Images

With Asciidoctor markup we can position images in our document. We can even float images, so text can next to an image, inside only below or about the image. We can also define multiple images to float, so the images are displayed on the same line next to each other. Any text that follows these images is also displayed next to the images. If we want only to have floating images, but the text starting under the images we can place the images inside an open block and assign the block the role float-group.

In the next example we first define three images that all have roles to float left. In the second part we group these images using the role float-group, so the text will not be displayed next to the images, but under the images:

:imagesdir: images/

= Grouping floats

// Images in open block to indicate 
// they belong together.
--
image::groovy.png[float="left"]
image::gradle.png[float="left"]
// Define float role, instead of attribute.
[.left]
image::grails.png[]
--

The images are all on one line,
but the text is next to the images.

If we want the images to be on one line,
but the text underneath them, we must use
a _float-group_ role, like in the
following example.

[.float-group]
--
image::groovy.png[float="left"]
image::gradle.png[float="left"]
// Define float role, instead of attribute.
[.left]
image::grails.png[]
--

The images above are all grouped together
to appear on one line.

And the text is not next to the images, but
underneath the images, like we wanted.

When we create a HTML document from the Asciidoctor markup we get the following result:

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Using Paragraphs in Lists With List Item Continuation

When we write a list in Asciidoctor we can simply create a list item by starting the line with a dot (.). To create a another list item we simply start a new line with a dot (.). But what if we want to add a list item with multiple paragraphs, or text and a source code block element. We can use the list item continuation (+) to indicate to Asciidoctor we want to keep these together for a single list item.

In the following example we have a list in Asciidoctor markup. The second list item has multiple paragraphs , the third item has an extra admonition block and the fourth item contains a source code block:

:icons: font

== List continuation

When we have a list item that has for example multiple paragraphs,
we can use Asciidoctor's list continuation feature. We place a
`+` symbol between the paragraphs to indicate the paragraphs
belong to a single list item.

=== Sample list

. A very simple first item
. This item consists of two paragraphs.
+
By adding the `+` symbol we indicate this
paragraph also belongs to the second list item.
. We can even add for example an admonition.
+
TIP: Did you know Asciidoctor is awesome?
. A small code example:
+
[source,groovy]
----
println 'Groovy rocks!'
----
. Let's end with a simple list item.

Let's generate this Asciidoctor markup to HTML and we see the following result:

We see how the extra paragraph, admonition and source code are part of a single list item.

Written with Asciidoctor 1.5.6.1.

Awesome Asciidoctor: Nested Tables

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:

= Tables

== 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
is processed.

[cols="1,2a"]
|===
| Col 1 | Col 2

| Cell 1.1
| Cell 1.2

| Cell 2.1
| Cell 2.2

[cols="2,1"]
!===
! Col1 ! Col2

! C11
! C12

!===

|===

When we run Asciidoctor to create HTML for this markup we get the following result:

Written with Asciidoctor 1.5.5.

Awesome Asciidoctor: Using Filename Starting With Dot As Block Title

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. We can also separate the first dot with the dotted filename with the document attribute {blank}. Also we can define the dot as document attribute and use it in the title. And finally we can define the filename via a document attribute and reference the document attribute in the block title:

= Filenames starting with dot (.)

Several samples showing how to set block title when title starts with dot (`.`).

Code block title is filename that starts with dot (`.`), which confuses the parser:

[source,json]
// Title cannot be parsed correctly
// because of the 2 dots.
..eslintrc
----
{
    "key": "value"
}
----

Using explicit title attribute:

// Instead of using . notation
// for block title, we use the
// explicit block attribute
// title definition.
[source,json,title='.eslintrc']
----
{
    "key": "value"
}
----

Use Unicode value for dot:

[source,json]
// Use hexadecimal Unicode replacement for
// starting dot (.) in filename.
..eslintrc
// (Or with decimals: ..eslintrc)
----
{
    "key": "value"
}
----

Format filename as code:

[source,json]
// Put filename between back ticks (`)
// and title is recognized again and
// nicely formatted with monotype font.
.`.eslintrc`
----
{
    "key": "value"
}
----

Using `\{blank}` document attribute to separate
title dot and filename:

[source,json]
// Separate title and filename with
// {blank} document attribute.
.{blank}.eslintrc
----
{
    "key": "value"
}
----

Using document attribute to define dot and use with filename:

[source,json]
// Section title is also parsed correctly
// if we use a document attribute
// to reflect dot.
:dot: .
.{dot}eslintrc
----
{
    "key": "value"
}
----

Using document attribute to set filename:

[source,json]
// Section title is also parsed correctly
// if we use a document attribute
// with the filename.
:snippetFilename: .eslintrc
.{snippetFilename}
----
{
    "key": "value"
}
----

[source,json]
// We can re-use the same document attribute
// for other code sections.
:snippetFilename: .jslintrc
.{snippetFilename}
----
{
    "key": "value"
}
----

When we generate a HTML version of this markup we get the following result:

Written with Asciidoctor 1.5.4

Awesome Asciidoctor: Change Number Style For Ordered Lists

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 arabic, loweralpha, upperalpha, lowerromann or upperroman. With the HTML5 backend we can also use decimal and lowergreek.

In the following example we have an ordered list where we set different block styles for the nested level:

= Nested numbering styles

. Services
[arabic]
.. Datastore
.. Mail

. Repositories
// Only HTML backend
[decimal]
.. PostgresDB
.. Redis

. Controllers
// Only HTML backend
[lowergreek]
.. API
.. Admin

. Software systems
// Or use upperalpha for upper case alphanumeric
[loweralpha]
.. OAuth

. Operatings systems
// Or use lowerroman for lower case roman
[upperroman]
.. Linux
[decimal]
... Server A
... Server B
.. macOS
.. Windows server

When we create the HTML output we have the following result:

Written with Asciidoctor 1.5.4.

Awesome Asciidoctor Notebook Is Updated

I've written a couple of new blog posts about Asciidoctor the last couple of months, so it was time to also update the Awesome Asciidoctor Notebook. If you've downloaded the book before, you can download the latest version. The book is free, so you can download it if you didn't download it before. The following subjects have been added to the new version:

• Replacements For Text To Symbols
• Use Counters in Markup
• Change Level Offset For Included Documents
• Use Captions For Listing Blocks
• Customize the Figure Captions
• Trick To Use Caption Labels And Numbers In References
• Source Syntax Highlighting With Prism
• Highlight Lines In Source Code Listings
• Changing Values for Default Captions
• Using Ruby Extensions With Asciidoctor Gradle Plugin

Awesome Asciidoctor: Using Ruby Extensions With Asciidoctor Gradle Plugin

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:

$ tree lib/
lib/
├── emoji-inline-macro
│   ├── extension.rb
│   ├── sample.adoc
│   └── twemoji-awesome.css
└── emoji-inline-macro.rb

1 directory, 4 files

In our build file we configure the asciidoctor task and use the requires method to define a dependency on the Ruby emoji-inline-macro.rb file:

// File: build.gradle
plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
}

asciidoctor {
    // Add requirement on Ruby extension.
    requires './lib/emoji-inline-macro.rb'
}

We are done. Next we create a sample Asciidoc markup document with the following content:

= Asciidoctor is awesome!

Writing with Asciidoctor makes me feel emoji:sunny[5x]

This sample is written while Devoxx BE is in progress, so
@DevoxxPeople: Enjoy your emoji:beers[]

We get the following HTML5 output when we run the asciidoctor task:

Written with Asciidoctor Gradle plugin 1.5.3.