Asciidoctor Tabs

An Asciidoctor.js extension that adds a tabs block to the AsciiDoc syntax.

Install

This package depends on the asciidoctor package (>= 2.2.0, < 3.0.0), but doesn’t declare it as a dependency. Therefore, you must install that package when installing this one.

$ npm i asciidoctor @asciidoctor/tabs

Syntax

A tabset is defined using a description list (dlist) enclosed in an example block annotated with the tabs style.

[tabs]
====
Tab A:: Contents of Tab A.

Tab B::
+
Contents of Tab B.

Tab C::
+
--
Contents of Tab C.

Contains more than one block.
--
====

You may choose to extend the block delimiter length from the typical 4 characters to 6 in order to avoid conflicts with any example blocks inside the tabs block (or just as a matter of style).

[tabs]
======
Tab A::
+
====
Example block in Tab A.
====

Tab B:: Just text.
======

Using this technique, you can also create nested tabsets.

[tabs]
======
Tab A::
+
Selecting Tab A reveals a tabset with Tab Y and Tab Z.
+
[tabs]
====
Tab Y:: Contents of Tab Y, nested inside Tab A.
Tab Z:: Contents of Tab Z, nested inside Tab A.
====

Tab B:: Just text.
======

Usage

CLI

$ npx asciidoctor -r @asciidoctor/tabs tabs.adoc

The asciidoctor command automatically registers the tabs extension when the package is required.

API

There are two ways to use the extension with the Asciidoctor.js API. In either case, you must require the Asciidoctor.js module (asciidoctor) before requiring this one.

You can call the exported register method with no arguments to register the extension as a global extension.

const Asciidoctor = require('asciidoctor')()

require('@asciidoctor/tabs').register()

Asciidoctor.convertFile('tabs.adoc', { safe: 'safe' })

Or you can pass a registry instance to the register method to register the extension with a scoped registry.

const Asciidoctor = require('asciidoctor')()

const registry = Asciidoctor.Extensions.create()
require('@asciidoctor/tabs').register(registry)

Asciidoctor.convertFile('tabs.adoc', { extension_registry: registry, safe: 'safe' })

You can also require @asciidoctor/tabs/extensions to access the Extensions class. Attached to that object are the Block, Docinfo.Style, and Docinfo.Behavior extension classes. You can use these classes to register a bespoke tabs extension.