Antora Navigation Orphans Checker

This project contains a Python and a Go implementation of a program used to check whether the nav.adoc file of an Antora documentation set contains orphans.

"Orphans" in this context, are files that exist in the modules/ROOT/pages folder but who aren’t referenced on the nav.adoc file.

Usage

Use the tool as follows:

$ go build
$ ./antora-nav-orphans-checker -help
Usage of ./antora-nav-orphans-checker:
  -antoraPath string
        Path to Antora document sources (default "/docs")
  -filename string
        File to analyze (default "/modules/ROOT/nav.adoc")
  -module string
        Module to analyze (default "ROOT")

By default the tool checks the "ROOT" module in the "/docs" folder.

./antora-nav-orphans-checker -antoraPath fixture

The tool exits with code 1 if some files are missing. The list of files is printed in the console. If no files are missing, the tool exists with code 0.

You can specify other modules (you must specify the corresponding -filename argument in that case too):

./antora-nav-orphans-checker -antoraPath fixture -module AnotherModule -filename /modules/AnotherModule/nav.adoc

The -filename argument can be a different file to check; in this case it is assumed to be a standard Asciidoc file, where files are referenced with include:: instead of xref:.

./antora-nav-orphans-checker -antoraPath fixture -filename /document.adoc

Container

This project generates a container that can be used as follows:

podman run --rm --volume "${PWD}":/antora ghcr.io/vshn/antora-nav-orphans-checker:main -antoraPath /antora/docs

Unit Tests

Run the suite of unit tests:

go test