Asciidoctor 1.5.8 comes with a really nice feature which is called autonumber callouts, so you do not have to specify the number of the callout, but just a generic character (.) and then at rendering time, Asciidoctor will set the name correctly.

See the next example shows the number and auto-number feature for callouts:

= My Code
:source-highlighter: highlightjs 

== Callouts

[source, java]
.MyClass.java
----
public class MyClass { // <1>
 public static void main(String[] args) { // <2>
 System.out.println("Hello World"); // <3>
 }

}
----
<1> Class name
<2> Entry point for a runnable JAR
<3> Prints to console

== Autonumber callout

[source, java]
.MyClass.java
----
public class MyClass { // <.>
 public static void main(String[] args) { // <.>
 System.out.println("Hello World"); // <.>
 }

}
----
<.> Class name
<.> Entry point for a runnable JAR
<.> Prints to console

And the output looks like:

So as you can see the output is exactly the same in both cases, but in the first case the number of the callout is static meanwhile in the second one autonumber feature is used.

Using autonumbering feature is really useful when you’ve got big blocks of code where you might introduce some callouts into already defined callouts which means a shifting of all of them.

Meanwhile, with the first approach means you need to go to every callout and increase the number manually, in the later one you only need to add a new callout and that’s all, you do not need to go manually increasing the callout number.

We keep learning,

Alex.

My body is burning, it starts to shout, Desire is coming, it breaks out loud (Rock You Like Hurricane – Scorpions)