@jti/doctools v1.1.24

jti-doctools

A group of useful tools for managing and building JTI documentation projects:

• Antora: a static site generator for technical documentation.
• Go-Task: a cross-platform build task coordinator.
• htmltest: a fast link checker for static websites.
• vale: a prose checker.
• Antora Assembler and Asciidoctor PDF: generates PDFs from Antora content.

Requirements

• Node.js, version 16.x or newer (for Antora and most tooling).
• Ruby, version 3.x or newer (for PDF generation).
• A documentation project repo with at least one commit. The Asciidoc source must by in an Antora-compatible folder structure inside the docs folder.

Installation

1. In a terminal window, use cd to enter the documentation project repo folder:

   cd /path/to/documentation/project

2. If you do not have a package.json file, create one:

   npm init -y

3. Install the doctools package:

   npm i @jti/doctools

   Be patient: it can take a couple of minutes to download and install the dependencies.

Usage

Preview

To generate the HTML, create search indexes, run the checks, and serve the HTML, run:

npx task local

Quick

If you just want to see the generated HTML/PDF, run:

npx task quick

None of the checks run, making the build a bit quicker.

Note that you can disabled PDF generation by editing the antora-playbook.yml file, and setting the enabled flag for the @antora/pdf-extension extension to false. PDF generation takes 10-1,000x the time required to generate HTML alone.

Authors

• Ewan Edwards (@jtiee)

Note: No claim of ownership is made for all the tools used in this package.

Many thanks to tool authors, and the authors of the many package dependencies, for making their technology available!