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.
