This extension automatically generates a Terminology section for Asciidoctor-PDF documents using Asciidoctor’s built-in Index feature.

https://baiyibai-antora.gitlab.io

This extension achieves three main goals:

  1. To ensure abbreviations are used consistently throughout documentation using the indexterm markup.
    This encourages authors to fully spell out a term on the first instance, and then use an abbreviated term in subsequent instances.

  2. Eliminate manual work.

  3. [Optional] Provide additional externally-curated, and centrally-maintained, definitions via a table with the .terminology role in the document AST.

Asciidoctor-PDF Standalone Usage Instructions

Complete these steps to use this extension:

  1. Clone this repository, or acquire the autogen-terminology.rb and add-table-roles.rb files along with the pdf-themes/table-roles-theme.yml file.

  2. Create an Asciidoctor document using the index terms.

  3. Include a table with the .terminology role containing definitions.
    See terminology-definitions.html for an example of the markup.
    The table should be included in your document using the include directive with tags:

    link:terminology-definitions.adoc[role=include]

    To control whether custom definitions are used, set the document attribute:

    :terminology-use-definitions: true
    Note

    • When custom terminology definitions are disabled (:terminology-use-definitions: false or not set), only index terms with abbreviations in parentheses (e.g., Application Programming Interface (API)) are included in the terminology section.

    • When enabled (:terminology-use-definitions: true), the table with .terminology role will be parsed from the AST and hidden from the rendered output using the table role extension and theme.

    • The :terminology-use-definitions: attribute defaults to false if not specified.

  4. [Asciidoctor-PDF Users] Create two sections at the end of the document, assigning one the [type=terminology] block attribute:

    link:antora-asciidoctor-autoterm.adoc[role=include]
    Note
    		 The title of the sections is not fixed.

  5. Copy the pdf-themes/table-roles-theme.yml file or create a theme that hides tables with the .terminology role.

  6. Render the document with this command:

    asciidoctor-pdf -r ./add-table-roles.rb -r ./autogen-terminology.rb \
  -a pdf-theme=table-roles -a pdf-themesdir=pdf-themes \
  antora-asciidoctor-autoterm.adoc

Antora Assembler w/Asciidoctor-PDF Usage Instructions

Antora Assembler users require an additional extension to add the Terminology and the Index, complete these steps:

  1. Complete the steps in Asciidoctor-PDF Standalone Usage Instructions until Add Two Sections.
    Skip that step and instead add the file antora-assembler-add-terminology-and-index.rb to execution directory.

    1. To remove section numbering, uncomment out the specified lines.

  2. Add -r add-table-roles.rb, -r antora-assembler-add-terminology-and-index.rb, and -r autogen-terminology.rb to the antora-assembler.yml’s `build/command section, or use require_relative for each file.

  3. Add the PDF theme attributes: -a pdf-theme=table-roles -a pdf-themesdir=pdf-themes (adjust paths as needed)

  4. Add two document attributes to either the antora.yml or antora-assembler.yml file:

    • include-terminology: true

    • include-index: true

      Note

      Enable/disable those attributes as desired.

  5. Render the Antora project.

Antora Assembler Background

More information on using the Index with Antora Assembler is available at these links:

Antora HTML Site: Resolving xref Targets for Terminology and Index

@baiyibai-asciidoctor/autoterm is an Antora Node.js extension that assists asciidoctor-pdf and antora-assembler. It registers publishable Terminology and Index stub pages, each with a nav.adoc entry tagged role=hidden, so xref targets to them resolve and the Assembler’s merge includes them in the same document. Starting at 1.0.5, the gem’s tree-processor finds each stub by its title and mutates it in place into the real section, instead of appending a duplicate. Wrap a source reference to either page in ifdef::loader-assembler[] and endif::[] so it renders only for the PDF build.

antora:
  extensions:
    - require: '@baiyibai-asciidoctor/autoterm'
Important

role=hidden carries no built-in meaning for Antora or its default UI. A consuming UI bundle’s nav template MUST skip rendering an item carrying that role, or the stub pages appear in the HTML site’s navigation. For a Handlebars-based UI bundle derived from @antora/ui-default, wrap the item in partials/nav-tree.hbs:

{{#unless (includes ./roles 'hidden')}}
  <!-- existing <li> markup -->
{{/unless}}

with an includes helper:

module.exports = (arr, val) => Array.isArray(arr) && arr.includes(val)