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

    Note, using [source,console] ensures that the $ prompt is not copied when the user clicks the clipboard icon that appears upon mouseover above the code block.

    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";

    Code blocks can be grouped in a parent block element.

    ====
    [source,n1ql]
    ----
    SELECT CONTAINS("N1QL is awesome", "N1QL") as n1ql,
           CONTAINS("N1QL is awesome", "SQL") as no_sql;
    ----
    
    [source,json]
    ----
    {
        "results": [
            {
                "n1ql": true,
                "no_sql": false
            }
        ]
    }
    ----
    ====

    Rendered as:

    SELECT CONTAINS("N1QL is awesome", "N1QL") as n1ql,
           CONTAINS("N1QL is awesome", "SQL") as no_sql;
    {
        "results": [
            {
                "n1ql": true,
                "no_sql": false
            }
        ]
    }

    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 (#).

    The callout list does not have to follow immediately after the code block containing the callouts. For example, you can include an introductory sentence or paragraph between the code block and the callout list.

    Instead of marking up each callout with its own number, such as <1>, <2>, <3>, you can use <.> for each callout. When you use this method, the callouts are numbered automatically.

    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[]
    ----

    You will find most of the SDK code samples included in $examples directories alongside the pages parent to the .adoc file that is calling them. Else you will find thim in a special devguide/examples module in each SDK docs repo. Using include:: adds a Git hub link on mouseover, which leads to the code file on the repo.

    For a tagged region of a source file, set the tags around the code sample using the comment characcter appropriate to the source language, such as // or #:

    [source,ruby]
    ----
    # tag::read-only[]
    options = Cluster::QueryOptions.new
    options.readonly = true
    cluster.query(
        'SELECT COUNT(*) AS airport_count FROM `travel-sample` WHERE type = "airport"',
        options)
    # end::read-only[]
    ----

    And add the appropriate [tag=] to the include::.

    .Read-only Query
    [source,json]
    ----
    include::example$query.rb[tag=read-only]
    ----

    Note that we aim to keep all code files in the examples directory runnable — or at least compilable — so if you are adding a snippet of code to an existing file, please test it.

    Additional Resources