Extensions

This page explains the integration of Asciidoctor Tabs Block, Asciidoctor Kroki, Antora Lunr(Search Bar) and Asciidoctor Emoji Extension into the HPC website.

Asciidoctor Tabs Block

The following files are responsible for generating tabs block in the HPC website. The files can be downloaded from the above link.

Repository

Relative File Path to Repository

docs-ui

src/js/vendor/07-behavior.js

docs-ui

src/css/tabs.css

docs-site

lib/tabs-block.js

  • You also need to import tabs.css inside the site.css like below.

Tabs Block
  • Also, you need to register the extension in antora-playbook.yml file in docs-site repository like below.

Tabs Block Playbook File

Asciidoctor Kroki

  1. The first step is to install the npm package and its dependency from the docs-site repository.

    Syntax:

    $ npm i asciidoctor asciidoctor-kroki
  2. The second step is to register the extension in your antora-playbook.yml file.

    Syntax:

    asciidoc:
      extensions:
      - asciidoctor-kroki

Please refer to → Asciidoctor Kroki Usage on how to use this extension in Asciidoc.

Antora Lunr(Search Bar)

This extension is responsible for adding a self-managed search powered by Lunr to HPC website.

Installation

  1. The first step is to install the npm package into the docs-site repository like below.

    Syntax:

    $ npm i @antora/lunr-extension
  2. The second step is to point the supplemental_files key in antora-playbook.yml file directly to the supplemental_ui directory of the installed npm package.

    Syntax:

    ui:
      supplemental_files: ./node_modules/@antora/lunr-extension/supplemental_ui
  3. Next, register the extension using the --extension CLI option of the antora command.

    Syntax:

    antora --extension @antora/lunr-extension antora-playbook.yml
  4. Also, you need to set the enviornmental variable, SITE_SEARCH_PROVIDER=lunr which is required to enable the search bar in the UI and the corresponding layout for the search bar is present in the custom-header-content.hbs layout file in the docs-ui repository.

  • custom-header-content.hbs

...
...
<div id="topbar-nav" class="navbar-menu">
    <div class="navbar-end">
    {{#if env.SITE_SEARCH_PROVIDER}}
    <div class="navbar-item search hide-for-print">
        <div id="search-field" class="field">
        <input id="search-input" class="navbar-item search-input" type="text" placeholder="Search...">
        </div>
    </div>
    {{/if}}
    ...
...
...

Asciidoctor Emoji Extension

This extension is responsible for adding emojis into the HPC website.

  1. The first step is to install the npm package and its dependency from the docs-site repository.

    Syntax:

    $ npm install asciidoctor.js asciidoctor-emoji
  2. The second step is to register the extension in your antora-playbook.yml file.

    Syntax:

    asciidoc:
      extensions:
      - asciidoctor-emoji

Usage

Use emoji: followed by the name of your emoji. For instance, the syntax for wink emoji is:

emoji:wink[]