Callouts

Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block.

Callout syntax

Each callout number used in a verbatim block must appear twice. The first use, which goes within the verbatim block, marks the line being annotated (i.e., the target). The second use, which goes below the verbatim block, defines the annotation text. Multiple callout numbers may be used on a single line.

The callout number (at the target) must be placed at the end of the line.

Here’s a basic example of a verbatim block that uses callouts:

Example 1. Callout syntax

[source,ruby]
----
require 'sinatra' <1>

get '/hi' do <2> <3>
  "Hello World!"
end
----
<1> Library import
<2> URL mapping
<3> Response block

The result of Example 1 is rendered below.

require 'sinatra' (1)

get '/hi' do (2) (3)
  "Hello World!"
end

1	Library import
2	URL mapping
3	Response block

Since callout number can interfere with the syntax of the code they are annotating, Asciidoctor provides several features to hide the callout numbers from both the source and the converted document. The sections that follow detail these features.

Copy and paste friendly callouts

In versions prior to Asciidoctor 0.1.4, when a reader visiting an HTML page generated by Asciidoctor selected source code from a listing that contained callouts and copied it, the callout numbers would get caught up in the copied text. If the reader pasted that code and tried to run it, likely the extra characters from the callouts would cause compile or runtime errors.

Asciidoctor uses CSS to prevent callouts from being selected.

On the other side of the coin, you don’t want the callout annotations or CSS messing up your raw source code either. You can tuck your callouts neatly behind line comments. Asciidoctor will recognize the line comments characters in front of a callout number, optionally offset by a space, and remove them when converting the document.

Here are the line comments that are supported:

Example 2. Prevent callout copy and paste

----
line of code // <1>
line of code # <2>
line of code ;; <3>
line of code <!--4-->
----
<1> A callout behind a line comment for C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure.
<4> A callout behind a line comment for XML or SGML languages like HTML.

The result of Example 2 is rendered below.

line of code (1)
line of code (2)
line of code (3)
line of code (4)

1	A callout behind a line comment for C-style languages.
2	A callout behind a line comment for Ruby, Python, Perl, etc.
3	A callout behind a line comment for Clojure.
4	A callout behind a line comment for XML or SGML languages like HTML.

XML callouts

XML doesn’t have line comments, so our “tuck the callout behind a line comment” trick doesn’t work here. To use callouts in XML, you must place the callout’s angled brackets around the XML comment and callout number.

Here’s how it appears in a listing:

Example 3. XML callout syntax

[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.

The result of Example 3 is rendered below.

<section>
  <title>Section Title</title> (1)
</section>

1	The section title is required.

Notice the comment has been replaced with a circled number that cannot be selected (if not using font icons it will be rendered differently and selectable). Now both you and the reader can copy and paste XML source code containing callouts without worrying about errors.

Callout icons

The font icons setting also enables callout icons drawn using CSS.

= Document Title
:icons: font (1)

NOTE: Asciidoctor now supports font-based admonition
icons, powered by Font Awesome! (2)

1	Activates the font-based icons in the HTML5 backend.
2	Admonition block that uses a font-based icon.