antora-shiki-extension v1.0.0

Antora Shiki Extension

Features

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

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.

📌 NOTE\ At the moment only Shiki in version 0.14.1 is supported. We have to evaluate if the newer Shiki versions can be used as well.

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.

Installation

Begin by installing the extension package into your playbook project:

$ npm i antora-shiki-extension

Usage

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:
    - require: '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

Configuration Options

The extension supports the following configuration options:

Callout Styling

When conums_override is enabled (default), the extension provides theme-aware callout styling:

• By default, callouts use a background color derived from the theme’s foreground color
• The text color is automatically chosen to ensure readability
• Borders are disabled by default but can be enabled with conums_show_border: true
• You can override both background and foreground colors using conums_bg_color and conums_fg_color

Example configuration with custom colors:

antora:
  extensions:
    - require: 'antora-shiki-extension'
      conums_override: true             # Enable custom styling
      conums_bg_color: '#4a5568'        # Dark slate background
      conums_fg_color: '#ffffff'        # White text
      conums_show_border: true          # Show borders

📌 NOTE\ If you simply want to use the callout style defined in your custom antora css please simply set conums_override to false.

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

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.

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

Overview

- 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](https://docs.asciidoctor.org/asciidoc/latest/verbatim/source-highlighter/#enable-line-numbering). |

### Examples

## How it works

### 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 &lt;pre>: `--shiki-background-color`

## 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
* Use custom CSS styling for callouts
* Use theme-aware callout colors with border
* Use custom callout colors
* Use dark theme callout colors

### Use custom CSS styling for callouts

**Antora Playbook**

```yaml
antora:
  extensions:
    - require: 'antora-shiki-extension'
      conums_override: false          # Use your custom CSS styling

Use theme-aware callout colors with border

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'
      conums_show_border: true        # Add borders to callouts

Use custom callout colors

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'
      conums_bg_color: '#2563eb'      # Blue background
      conums_fg_color: '#ffffff'      # White text

Use dark theme callout colors

Antora Playbook

antora:
  extensions:
    - require: 'antora-shiki-extension'
      conums_bg_color: '#1e293b'      # Dark slate background
      conums_fg_color: '#94a3b8'      # Light gray text
      conums_show_border: true        # Add subtle border

Default usage with default theme: nord

Antora Playbook

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

Change default theme to darcula in Antora playbook

Antora Playbook

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

Result

Change theme on page level

Antora Playbook

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

Page level theme definition

= Page Title
:shiki-theme: dracula

Result

Change theme on single source block

Antora Playbook

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

Source Block theme definition

function helloWorld() {
  console.log('Hello World');
}

Result

Enable line numbers on source block

Antora Playbook

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

function helloWorld() {
  console.log('Hello World');
}

Result

Enable line numbers on specific page

Antora Playbook

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

= Page Title
:shiki-line-numbers: true

Result

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

Enable line numbers on all pages

Antora Playbook

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

Disable line numbers on single source block

Antora Playbook

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

function helloWorld() {
  console.log('Hello World');
}

Result

Disable line numbers on specific page

= Page Title
:shiki-line-numbers: false

Line numbers with specific beginning

Antora Playbook

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

function helloWorld() {
  console.log('Hello World');
}

Result

More informations

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

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.

Trademarks

AsciiDoc(R) is a trademark of the Eclipse Foundation, Inc.