This document explains how to integrate Asciidoctor Tabs into your Antora-based documentation site.
The first step is to incorporate the behavior and style into your UI. These instructions assume your UI was created based on the Antora default UI project template.
First, declare a dependency on this package in package.json for your Antora UI project:
$ npm i -D @asciidoctor/tabs
Next, define a vendor stylesheet at src/css/vendor/tabs.css and populate it with the following content:
@import "@asciidoctor/tabs"postCSS will know how to resolve the stylesheet from the npm package name based on metadata provided by the package. This assumes the build task in your UI project is set up to process vendor files (i.e., src/css/vendor/*.css).
Next, add the following line to the bottom of the src/partials/head-styles.hbs to link to the stylesheet from the HTML pages.
|
💡
|
You can add the @import line to the bottom of the existing src/css/site.css file.
In that case, you don’t have to add a link to the vendor stylesheet in your template.
You could also forgo the use of the provided CSS and develop your own CSS instead.
|
Next, define a vendor script at src/js/vendor/tabs.bundle.js and populate it with the following content:
require('@asciidoctor/tabs')browserify will know how to resolve the script from the npm package name based on metadata provided by the package. This assumes the build task in your UI project is set up to process vendor files (i.e., src/js/vendor/*.bundle.js).
Next, append the following line to the bottom of the src/partials/footer-scripts.hbs to link to the script from the HTML pages.
|
Important
|
Do not remove any of the other lines in src/partials/footer-scripts.hbs or else other features of the site will stop working! |
|
💡
|
Alternately, you can move src/js/vendor/tabs.bundle.js to src/js/10-tabs.js so it gets bundled into site.js.
In this case, you don’t need to add the additional <script> tag.
|
The next time you bundle your UI, it will be ready to be used with the Asciidoctor Tabs extension!
If you’re using tabs sync, and you want the selected tab to persist across pages, you can enable this behavior by specifying a configuration option in the form of a data attribute on the script tag.
By default, the selected tab is saved in local storage.
To use session storage instead, add the attribute data-sync-storage-scope="session" to the script tag.
|
💡
|
In order to use tabs in the UI preview, you need to add the following key to the top of preview-src/ui-model.yml: asciidoc:
extensions:
- '@asciidoctor/tabs'The UI preview builder will require each entry and invoke the |
Now that your UI is set up to support tabs, you need to enable the extension when generating your site. To do so, you once again need to declare a dependency on this package in package.json for your Antora playbook project:
$ npm i @asciidoctor/tabs
Next, configure Antora to require the package after initializing Asciidoctor by adding the following to your playbook file:
asciidoc:
extensions:
- '@asciidoctor/tabs'|
📎
|
If the asciidoc key or asciidoc.extensions keys already exist, merge this entry with the existing key.
|
You can now use Asciidoctor Tabs in your Antora-based documentation!
Instead of maintaining a separate UI project, you can integrate Asciidoctor Tabs directly into your playbook project using Antora’s supplemental UI feature.
First, declare a dependency on this package in package.json for your Antora playbook project:
$ npm i @asciidoctor/tabs
Next, configure Antora to require the package after initializing Asciidoctor by adding the following to your playbook file:
asciidoc:
extensions:
- '@asciidoctor/tabs'|
📎
|
If the asciidoc key or asciidoc.extensions keys already exist, merge this entry with the existing key.
|
Next, define the assets exported by Asciidoctor Tabs as supplemental UI files and reconfigure the template partials to reference them.
You can either define the files directly in the playbook, as shown below, or you can put them in a supplemental UI folder and specify the path to that folder using the supplemental_files key.
ui:
supplemental_files:
- path: css/vendor/tabs.css
contents: ./node_modules/@asciidoctor/tabs/dist/css/tabs.css
- path: js/vendor/tabs.js
contents: ./node_modules/@asciidoctor/tabs/dist/js/tabs.js
- path: partials/footer-scripts.hbs
contents: |
<script id="site-script" src="{{{uiRootPath}}}/js/site.js" data-ui-root-path="{{{uiRootPath}}}"></script>
<script async src="{{{uiRootPath}}}/js/vendor/highlight.js"></script>
<script async src="{{{uiRootPath}}}/js/vendor/tabs.js"></script>
{{#if env.SITE_SEARCH_PROVIDER}}
{{> search-scripts}}
{{/if}}
- path: partials/head-styles.hbs
contents: |
<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
<link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/tabs.css">|
📎
|
The paths used in this example assume that the @asciidoctor/tabs npm package is installed in your project and that your Antora playbook file is located adjacent to package.json and the node_modules directory.
If it’s installed somewhere else, you’ll need to tune the path to the node_modules directory accordingly (replacing ./node_modules/).
You can use either relative or absolute paths.
|
If the ui key or ui.supplemental_files keys already exist, merge this entry with the existing key.
On the other hand, if you already have a supplemental UI that’s being loaded from a directory (e.g., supplemental-ui), you won’t be able to define the supplemental files that support Asciidoctor Tabs directly in your playbook. Instead, you’ll need to create these files in your supplemental UI folder instead. For the two files that are sourced from node_modules, you’ll need to create symlinks to them.
$ ln -s node_modules/@asciidoctor/tabs/dist/css/tabs.css supplemental-ui/css/vendor/tabs.css $ ln -s node_modules/@asciidoctor/tabs/dist/js/tabs.js supplemental-ui/js/vendor/tabs.js
You can now use Asciidoctor Tabs in your Antora-based documentation!