An Asciidoctor.js extension that adds a tabs block to the AsciiDoc syntax.
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
If you’re using the extension with Antora, there’s no need to install the asciidoctor package as Antora provides it.
See the Antora integration guide to learn how to integrate this extension into an Antora site.
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.
======$ npx asciidoctor -r @asciidoctor/tabs tabs.adoc
The asciidoctor command automatically registers the tabs extension when the package is required.
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.
See the Antora integration guide to learn how to integrate this extension into an Antora site.