Awesome Asciidoctor: Highlight Lines In Source Code Listings

In Asciidoctor we can configure syntax highlighting for our source code listings. We can choose from the built-in support for Coderay, Pygments, highlight.js and prettify. The syntax highlighter libraries Coderay and Pygments support extra highlighting of lines, so we can add extra attention to those lines. In this post we see how to use the line highlighting feature in Asciidoctor.

First we must add the document attribute source-highlighter and use the value coderay or pygments. When we use Coderay we must also enable the line numbers for the source code listing, because Coderay will highlight the line numbers in the output. Pygments highlight the whole line, with or without line numbers in the output. Therefore we choose Pygments in our example. To highlight certain lines in the source code output we use the highlight attribute for the source code block. We can specify single line numbers separated by a comma (,) or semi colon (;). If we use a comma we must enclose the value of the highlight attribute in quotes. To define a range of line numbers we can define the start and end line numbers with a hyphen in between (eg. 5-10 to highlight lines 5 to 10). To unhighlight a line we must prefix it with a exclamation mark (!). For example the following value for the highlight attribute highlights the lines 2, 3 to 7 and not 5: [source,highlight=1;3-7;!5].

In the following example markup we have a source code block where we highlight the lines 7 to 9. We use Pygments as syntax highlighter:

= Source highlight lines
:source-highlighter: pygments
:pygments-style: emacs
:icons: font

== Creating an application

To create a simple Ratpack application we write
the following code:

.Simple Groovy Ratpack application
[source,groovy,linenums,highlight='7-9']
----
package com.mrhaki

import static ratpack.groovy.Groovy.ratpack

ratpack {
    handlers {
        get {
            render "Hello World!" // <1>
        }
    }
}
----
<1> Render output

If we look at the generated HTML we can see lines 7, 8 and 9 are differently styled:

Written with Asciidoctor 1.5.4.

Awesome Asciidoctor: Source Syntax Highlighting With Prism

Asciidoctor has built-in support for a couple of source syntax highlighting libraries like Coderay, Pygments, highlight.js and prettify. In this post we learn how to use the Javascript library Prism to do the syntax highlighting for our source blocks. Because Prism is a Javascript library we must remember this only works for the HTML backend of Asciidoctor.

In the following markup we have two source code listings in Java and Groovy:

= Source highlights with Prism
// Set default language for source code listings to java.
:source-language: java
// Include docinfo.html for Prism CSS file and
// include docinfo-footer.html for Prism Javascript.
:docinfo1:

== Creating an application

To create a simple Ratpack application we write
the following code:

.Simple Java Ratpack application
[source]
----
package com.mrhaki;

import ratpack.server.RatpackServer;

public class Main {
    public static void main(String... args) throws Exception {
        RatpackServer.start(server ->
            server
                .handlers(chain ->
                    chain
                        .get(ctx -> ctx.render("Hello World!"))));
    }
}
----

.Simple Groovy Ratpack application
[source,groovy]
----
package com.mrhaki

import static ratpack.groovy.Groovy.ratpack

ratpack {
    handlers {
        get {
            render "Hello World!"
        }
    }
}
----

Each source listing is transformed to HTML with the following structure:

<pre class="highlight"><code class="language-{language}" data-lang="{language}">
{code}
</code></pre>

This fits perfectly with Prism. Prism expects this format to apply the syntax highlighting. So we only have to add the Prism Javascript and CSS files to the generated HTML file. We download the Prism Javascript and CSS file from the Prism download site. We save the Javascript file as prism.js and the CSS file as prism.css. Next we create a docinfo.html to include a reference to the prism.css file:

<link href="prism.css" rel="stylesheet" />
<style>
/* Override Asciidoctor CSS to get the correct background */
.listingblock pre[class^="highlight "] {
    background: #272822;
}
</style>

We also create the file docinfo-footer.html to reference prism.js:

<script src="prism.js"></script>

In our markup we have the document attribute docinfo1 set. This means the files docinfo.html and docinfo-footer.html are included in the generated HTML output. Let's see the result in a web browser:

Written with Asciidoctor 1.5.4.