= Asciidoctor Tabs Dan Allen https://github.com/mojavelinux[@mojavelinux] v1.0.0-beta.6, 2023-08-01 :idprefix: :idseparator: - ifndef::env-github[:icons: font] ifdef::env-github[] :note-caption: :paperclip: :tip-caption: :bulb: endif::[] :url-repo: https://github.com/asciidoctor/asciidoctor-tabs
An Asciidoctor extension that adds a tabs block to the AsciiDoc syntax.
NOTE: This extension is intended to be used with HTML backends (e.g., html5).
For all other backends (i.e., the filetype is not html), the custom block enclosure is discarded and its contents (a dlist) is converted normally.
TIP: This extension is also published as an npm package named @asciidoctor/tabs for use with Asciidoctor.js, and hence, with Antora.
See the xref:js/README.adoc[README] for the npm package and its xref:docs/use-with-antora.adoc[Antora integration guide] for details.
== Overview
Each set of tabs (i.e., a "tabset" or tabs block) is constructed from a description list (dlist) enclosed in an example block annotated with the tabs style (i.e., [tab]).
That nested combination of blocks gets translated by this extension into a single tabs block that is a specialization of an open block.
The tabbed interface produced from this block can help organize information by code language, operating system, or product variant. The benefit of organizing information in this way is that it condenses the use of vertical space by only showing what's relevant to the reader (and thus hiding information that's irrelevant or redundant). The result is that readers enjoy a better user experience when reading your documentation.
== Install
=== Using gem command
$ gem install --prerelease asciidoctor-tabs
=== Using Bundler
Create a [.path]Gemfile in your project:
source 'https://rubygems.org'
gem 'asciidoctor-tabs'
Then optionally configure Bundler to install gems locally:
$ bundle config --local path .bundle/gems
Then use Bundler to install the gem:
$ bundle
== Syntax
A tabset is defined using a description list (dlist) enclosed in an example block annotated with the tabs style.
Tab A:: Contents of Tab A.
Tab B:: + Contents of Tab B.
Contents of Tab C.
The tabs themselves are modeled as a dlist. Each item in the dlist becomes a separate tab. The term is used as the tab's label and the description is used as the tab's contents. The contents can be defined as primary text, attached blocks, or both. If the tab has a single attached block, and that block is an open block with no attributes, the open block enclosure itself is discarded upon conversion.
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).
Using this technique, you can also create nested tabsets.
== Tabs Sync
If you want to synchronize (i.e., sync) the tab selection across tabsets, set the tabs-sync-option on the document.
:tabs-sync-option:
...
Only tabsets that have the same sync group ID are synchronized.
By default, the sync group ID is computed by taking the text of each tab, sorting that list, and joining it on | (e.g., A|B).
Each unique combination of tabs--or congruent tablist--implicitly creates a new sync group.
You can override the sync group ID of a tabset using the sync-group-id attribute on the block.
This allows you to control the scope of the sync or to force a tabset to participate in a sync group even if its not congruent.
:tabs-sync-option:
Instead of enabling tabs sync globally, you can set the sync option on individual tabs blocks.
Conversely, if you want to delist a tabs block from the global sync, set the nosync option on that block.
:tabs-sync-option:
If you want to persist the sync selection, assign a value to the data-sync-storage-key attribute on the <script> tag.