Code Blocks

This page describes some of the styles and behaviors of code blocks and how to support them in a custom UI.

In AsciiDoc, code blocks a referred to as source and listing blocks. A source block is a listing block that has a source language defined on it (e.g., javascript). Refer to source blocks to learn more about source blocks in AsciiDoc and how they are used in Antora.

Readers typically expect that a source block will be presented with syntax highlighting, so we’ll start there.

Syntax highlighting

Antora uses highlight.js as syntax highlighter in the AsciiDoc processor by default.

If you want to turn off syntax highlighting, you can do so by unsetting the source-highlighter attribute in the Antora playbook.

asciidoc:
  attributes:
    source-highlighter: ~

If you soft unset the value instead (i.e., set the value to false), it allows individual pages to selectively turn syntax highlighting back on.

By default, Antora highlights a restricted set of languages in order to minimize the size of the supporting asset files. However, you can add or remove support for languages in your own UI bundle. To do so, follow these steps:

  1. Switch to your UI project.

  2. Open the file src/js/vendor/highlight.bundle.js.

  3. Add or remove one of the registerLanguage statements.

For example, to add AsciiDoc syntax highlighting, add the following line:

  hljs.registerLanguage('asciidoc', require('highlight.js/lib/languages/asciidoc'))

Keep in mind, the language must be supported by highlight.js. To find out what languages are supported and how to abbreviate them, set the languages folder in the project on GitHub.

Copy to clipboard

This page describes the copy to clipboard feature added to source blocks when using the default UI.

Source blocks

The default UI automatically adds a clipboard button to all source blocks and provides the necesssary CSS and JavaScript to support that behavior. The clipboard button shows up next to the language label when the mouse is hovered over the block. When the user clicks the clipboard button, the contents of the source block will be copied to the user’s clipboard and a notification overlay will be briefly shown.

You can try this behavior below:

puts 'Take me to your clipboard!'
Copy to clipboard only works for a local site or if the site is hosted over https (SSL). The copy to clipboard does not work on an insecure site (http) since the clipboard API is not available in that environment. In that case, the behavior gracefully degrades so the user will not see the clipboard button or an error.

Console blocks

The default UI also adds a clipboard button to all console blocks. A console block is either a literal paragraph that begins with a $ or a source block with the language console.

The script provided by the default UI will automatically strip the $ prompt at the beginning of each line and join the lines with &&. In Copy to clipboard for a multi-line console command, since the language is console and each line begins with a $, the console copy-paste logic is triggered.

Copy to clipboard for a multi-line console command
[,console]
----
$ mkdir example
$ cd example
----

When a user uses the copy-to-clipboard button, they will copy the combined command mkdir example && cd example instead of the literal text shown. This can be useful for tutorial examples that a user is expected to copy-paste to run. You can try this behavior below:

$ mkdir example
$ cd example