Antora Shiki Extension

Contents

• 1. Features
• 2. Why Shiki instead of Highlight.js?
• 3. Prerequisites
• 4. Installation
• 5. Usage
  • 5.1. Register the extension
  • 5.2. Add handlebars templates
• 6. Configuration
  • 6.1. Overview
  • 6.2. Examples
• 7. How it works
  • 7.1. Process
• 8. Use Cases
  • 8.1. Default usage with default theme: nord
  • 8.2. Change default theme to darcula in Antora playbook
  • 8.3. Change theme on page level
  • 8.4. Change theme on single source block
  • 8.5. Enable line numbers on source block
  • 8.6. Enable line numbers on specific page
  • 8.7. Enable line numbers on all pages
  • 8.8. Disable line numbers on single source block
  • 8.9. Disable line numbers on specific page
  • 8.10. Line numbers with specific beginning
• 9. More informations
• 10. Acknowledgements
• 11. Trademarks

1. Features

This extension wants to make it easier to use Shiki in Antora projects. It offers the following features:

Feature	Description
Build-time rendering	When Antora renders the site it will already have the syntax highlighted code blocks. No javascript needed on client.
Full Shiki Support	All Shiki Languages and Shiki Themes are supported.
Adds Asciidoc grammar to Shiki	Shiki does not offer an Asciidoc grammar. This extension adds the Asciidoc grammar to Shiki which is used by the Asciidoctor VS Code Extension.
Supports custom grammar for Shiki	It is possible to register your own grammar files for languages.
Multi-Theme Support	You can define a different theme for each page or even multiple themes on one page.
Line Numbering	You can enable line numbering for each code block or for all pages by supporting the line number capabilities of Asciidoctor
Dynamic Line Number color	Depending on the used background color of the theme the line number color will be adjusted to be better readable.

2. Why Shiki instead of Highlight.js?

Shiki is a syntax highlighter powered by the same language grammars used in Visual Studio Code, ensuring accurate and consistent code coloring. It offers a wide range of themes and can tokenize code in any language that VS Code supports, making it highly versatile. Unlike many highlighters, Shiki pre-processes code into colored HTML at build time, offering improved performance and consistency across different environments.

Benefits

• Accurate Syntax Highlighting: Shiki uses the same language grammars as Visual Studio Code, ensuring highly accurate and consistent syntax highlighting.

• Build-Time Rendering: Shiki processes code into colored HTML at build time, which can improve page load performance and ensures consistent rendering across different browsers and environments.

• Wide Range of Themes: Shiki supports a broad array of themes directly from Visual Studio Code, offering more variety and customization options.

• Consistent with VS Code: Developers familiar with Visual Studio Code will find Shiki’s highlighting consistent with their development environment, making it easier to integrate into documentation or blogs.

• Extensive Language Support: Shiki can tokenize code in any language supported by VS Code, offering extensive language support.

• Minimal Client-Side Processing: Since Shiki does the heavy lifting at build time, there is minimal processing required on the client-side, leading to better performance especially on less powerful devices.

3. Prerequisites

In order to use this extension, you must be using at least Node.js 16 and Antora 3. We assume you’ve already set up an Antora playbook file (i.e., antora-playbook.yml) to build your site.

4. Installation

Begin by installing the extension package into your playbook project:

$ npm i antora-shiki-extension

5. Usage

5.1. Register the extension

After installing the shiki extension package, you need to register the extension with Antora.

To register the extension, you’ll add an entry that cites the name of the package to the antora.extensions key in your Antora playbook file.

Open the Antora playbook file and add the extension as follows:

antora-playbook.yml

antora:
  extensions:
    - 'antora-shiki-extension' #(1)

asciidoc:
  attributes:
    source-highlighter: shiki #(2)

1. Register the antora extension

2. Set the source-highlighter to shiki

In order to specify configuration keys for the extension, you must change the entry to a map syntax. When using the map syntax, the package name must be preceded by the require key, as shown here:

antora-playbook.yml

antora:
  extensions:
  - require: 'antora-shiki-extension'

asciidoc:
  attributes:
    source-highlighter: shiki

You may want to start with this syntax so you don’t have to remember to switch to it later when you want to specify configuration.

5.2. Add handlebars templates

You have to change 1 file in your Antora UI bundle or by overwriting it via supplemental-ui:

• add {{> shiki-styles }} to partials/head-styles.hbs

5.2.1. Add to head-styles.hbs

head-styles.hbs

<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
{{> shiki-styles }}

{{> shiki-styles }} will be replaced with the content of the file shiki-styles.hbs that provided by this extension.

shiki-styles.hbs

<link rel="stylesheet" href="{{{uiRootPath}}}/css/shiki.css">

The shiki.css file contains some shiki specific styles that are needed to render the code blocks correctly and overrides some styles defined in the Antora UI Default.

6. Configuration

Minimal extension configuration

antora:
  extensions:
    - require: 'antora-shiki-extension'
      # theme: nord
      # themes: []
      # languages: ["asciidoc", "bash", "console", "diff", "java", "js", "shell", "yaml", "xml", "zsh"]
      # use_line_numbers: false

Full extension configuration

antora:
  extensions:
    - require: "antora-shiki-extension"
      theme: "darcula" # default: "nord"
      themes: ["material-theme", "dracula", "slack-dark", "github-light"] # default: []
      languages: # default: see this list
        - bash
        - console
        - diff
        - java
        - js
        - shell
      register_languages: # default: []
        - id: 'xml'
          scope_name: 'text.xml'
          grammar_path: ./relative-path-to-grammar-file
          alias: ['xml']
      use_line_numbers: true # default: false

6.1. Overview

Configuration key	Details
theme	Default: nord Set the default theme that should be used when no theme is defined on the asciidoc pages.
themes	Default: [] Defines all themes that should be loaded into the highlighter. Those can then be used on the asciidoc pages by defining the shiki-theme attribute.
languages	Default: ["asciidoc", "bash", "console", "diff", "java", "js", "shell", "yaml", "xml", "zsh"] Defines which languages are known to shiki. Note The id of the registered language must not be put into the languages array. The languages list is for defining the default languages provided by shiki. The register_languages array is for adding additional languages.
register_languages	Default: [] Defines an array of additional languages that should be registered to shiki. The array must contain objects with the following keys: id The id of the language scope_name The scope name of the language (see grammar file) grammar_path The path to the grammar file (relative to the playbook) alias (optional) An array of aliases for the language (see grammar file or add additional) Example - id: 'xml' scope_name: 'text.xml' grammar_path: ./relative-path-to-grammar-file alias: ['xml'] Note The id of the registered language must not be put into the languages array. The languages list is for defining the default languages provided by shiki. The register_languages array is for adding additional languages.
use_line_numbers	Default: false If set to true it will always use line numbers for all code blocks. You can also enable line numbers for each code block. Check here.

6.2. Examples

7. How it works

7.1. Process

The extension is called by Antora during the build process. It will then do the following steps:

• validate the configuration

• create the asciidoctor syntax highlighter for shiki and register it

• pass the extension context (logger, config, etc.) to the asciidoctor syntax highlighter

• copy the shiki.css to the uiCatalog

• copy the shiki-styles.hbs to the uiCatalog

• renders each asciidoc page with source blocks (ShikiSyntaxHighlighter)

  • calculate the current theme based on the page attributes (shiki-theme) and the configuration

  • generate the html code for the source block by using the shiki highligher

  • get the background color from the used theme

  • calculate if line numbers should be used

  • calculate the line number color based on the background color

  • remove the generated surrounding <pre><code> elements

  • create new <pre><code> elements with the calculated background color and the generated html code

    • sets css variables on <pre>: --shiki-background-color

8. Use Cases

The following use cases will be shown:

• Default usage with default theme: nord

• Change default theme to darcula in Antora playbook

• Change theme on page level

• Change theme on single source block

• Enable line numbers on source block

• Enable line numbers on specific page

• Enable line numbers on all pages

• Line numbers with specific beginning

• Disable line numbers on single source block

• Disable line numbers on specific page

8.1. Default usage with default theme: nord

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'

8.2. Change default theme to darcula in Antora playbook

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'
      theme: 'dracula'

Figure 1. Result

8.3. Change theme on page level

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'

Page level theme definition

= Page Title
:shiki-theme: dracula

Figure 2. Result

8.4. Change theme on single source block

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'

Source Block theme definition

[source,javascript,theme=dracula]
----
function helloWorld() {
  console.log('Hello World');
}
----

Figure 3. Result

8.5. Enable line numbers on source block

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'

[source,javascript,linenums]
----
function helloWorld() {
  console.log('Hello World');
}
----

Figure 4. Result

8.6. Enable line numbers on specific page

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'

= Page Title
:shiki-line-numbers: true

Figure 5. Result

You can also unset it via !shiki-line-numbers: like the theme.

8.7. Enable line numbers on all pages

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'
      use_line_numbers: true

8.8. Disable line numbers on single source block

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'
      use_line_numbers: true

[source,javascript,nolinenums]
----
function helloWorld() {
  console.log('Hello World');
}
----

Figure 6. Result

8.9. Disable line numbers on specific page

= Page Title
:shiki-line-numbers: false

8.10. Line numbers with specific beginning

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'

[source,javascript,linenums,start=2]
----
function helloWorld() {
  console.log('Hello World');
}
----

Figure 7. Result

9. More informations

• Playground for Shiki Themes. Please check it out if you want to know what is possible.

10. Acknowledgements

• antora-lunr-extension that helped me to understand how to write an Antora extension and offered me a lot of inspiration.

• Shiki project for their great work

• Shiki PR that describes how create line numbers via css.

11. Trademarks

AsciiDoc® is a trademark of the Eclipse Foundation, Inc.