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: