Code Blocks and Callouts

Code Blocks

Source code examples are entered into AsciiDoc listing blocks. Listing block content is displayed exactly as entered, and any indents and endlines are preserved. If the source style and a language are assigned to the block, the code is syntax highlighted on the site.

Delimited code block with title
.Optional title
[source,java] (1) (2)
--(3)
KStreamBuilder builder = new KStreamBuilder();

KStream<String, GenericRecord> source = builder
        .stream("streaming-topic-beer-sample");
----
1 Assign the block style source to the first position in the attribute list.
2 Assign a source language to the second position.
3 Code the contains blank lines must be entered into a delimited listing block (----).

Rendered as:

Optional title
KStreamBuilder builder = new KStreamBuilder();

KStream<String, GenericRecord> source = builder
        .stream("streaming-topic-beer-sample");

Commands executed in a CLI are assigned the language console and lines are preceded by the command prompt ($).

[source,console]
----
$ curl GET -u admin:password http://ip.for.destination.cluster:8091/pools/default/buckets
----

Rendered as:

$ curl GET -u admin:password http://ip.for.destination.cluster:8091/pools/default/buckets

Short code snippets don’t need delimiters as long as they don’t contain blank lines or callouts.

[source,sql]
SELECT country FROM `travel-sample` WHERE name = "Excel Airways";

Rendered as:

SELECT country FROM `travel-sample` WHERE name = "Excel Airways";

Callout Numbers

Callouts add annotations to lines in code blocks. The first callout number must be placed after the final character on a code line. The responding callout is listed below the block and followed by the annotation text. Multiple callout numbers can be used on a single line.

[source,javascript]
----
function OnUpdate(doc, meta) {
  var strong = 70;
  var stmt =
    SELECT *                  // <1>
    FROM `beer-samples`       // <2>
    WHERE abv > $strong;
  for (var beer of stmt) {    // <3>
    break;                    // <4>
  }
}
----
<1> N1QL queries are embedded directly.
<2> Token escaping is standard N1QL style.
<3> Stream results using 'for' iterator.
<4> Cancel streaming query by breaking out.

Rendered as:

function OnUpdate(doc, meta) {
  var strong = 70;
  var stmt =
    SELECT *                  (1)
    FROM `beer-samples`       (2)
    WHERE abv > $strong;
  for (var beer of stmt) {    (3)
    break;                    (4)
  }
}
1 N1QL queries are embedded directly.
2 Token escaping is standard N1QL style.
3 Stream results using 'for' iterator.
4 Cancel streaming query by breaking out.
To make callouts copy-and-paste friendly, put them behind the line comment syntax of the code snippet’s language. For example, callouts in a YAML example are placed behind the hash symbol (#).

Inserting Examples with the Include Directive

The include directive inserts an entire file or tagged region from a file stored in the examples directory of a module into a code block. Just specify the resource ID of the example file in the directive.

.Query result
[source,json]
----
include::example$contact.json[]
----

Learn More

Additional Resources

The Antora and Asciidoctor documentation provide more information about including code examples.