This repo is primarily a Node.js-based set of tools to help build Antora-based documentation.

Antora does most of the work, but the tools also include:

• A set of Antora extensions that implement content checks for:

  • Repeated words.

  • Asciidoc formatted as "ventilated prose".

  • Image existence and size declarations.

  • A set of opinionated language style checks for technical documentation.

Each of the extensions can be independently enabled/disabled, and each features a "debug" mode.

• Spelling and language checks using Vale.

• Link ("local" and external) using htmltest.

• Search using Pagefind.

• PDF generation using Asciidoctor PDF.

• Node.js 16.x or newer.

• Ruby 3.x or newer (for PDF generation).

• Docker

• make

Documentation builds should work fine on macOS, Linux, and Windows. Only macOS builds have been tested to date.

• Ensure that the requirements have been met.

• Create a Git repository with a docs folder at the root containing Antora-compatible documentation structure.

• If you do not have a package.json file, in the repo root run:

  npm init -y

1. In your documentation Git repo root, run:

   npm i https://github.com/eskwayrd/antora-doc-tools

2. If your repo does not already have a .gitignore file, ADT installs one for you that is suitable for an Antora documentation project.

3. If your repo does not already have a Vale folder, ADT creates one and creates the necessary styles folder and .vale.ini file inside.

   Once .vale.ini exists, you should customize it to include Vale style packages that your project requires. You can install styles from the Vale Package Hub.

   Once customize, commit .vale.ini, but not the style folders.

4. If your repo does not already have an htmltest.yml config file, ADT creates one for you. You likely do not need to customize the configuration, but you should commit the file.