asciidoc-aware-link-check

A source file link validation tool for documentation written in Asciidoc.

Intended usage

The asciidoc-aware-link-check program is suitable for testing the validity of external links in your AsciiDoc files. The program uses Asciidoctor.js internally so that attributes are resolved.

Prerequisites

Nodejs >= 10

Installation

To install the application, enter the following command:

npm i -g @jboxman/asciidoc-aware-link-check

Usage

To learn about supported options, enter the following command:

$ asciidoc-aware-link-check --help
Usage: asciidoc-aware-link-check [options]

Options:
  -a, --attributes [attributes...]  Optional: Attributes such as "product-version=1".
  --csv                             Output to stdout in CSV format. Outputs BROKEN_LINK,MODULE,LINE_NUM. This option
                                    implies --no-progress and --quiet.
  -n, --dry                         Dry run.
  --no-progress                     Hide progress bar.
  -q, --quiet                       Display errors only.
  --stdin                           Read file list from stdin instead of a _topic_map.yml file. (default: false)
  --topic <path>                    Optional: Path to ascii_binder _topic_map.yml file.
  -h, --help                        display help for command

To validate links, enter the following command. Replace <ASSEMBLY_FILE> with the file name that includes any include statements needed to successfully build your documentation.

$ echo <ASSEMBLY_FILE> | asciidoc-aware-link-check --stdin

To validate links for your entire documentation set, you might enter the following the command. Replace <ASSEMBLY_DIR> with the directory where you save your assembly files.

$ find <ASSEMBLY_DIR> -type f -name '*.adoc' | asciidoc-aware-link-check --stdin

Examples

The following examples illustrate a documentation set of some complexity and the output from asciidoc-aware-link-check when run against that documentation set.

Example documentation set

The following documentation subset uses common AsciiDoc functionality, including attributes and includes. The output and files are snipped for brevity.

Directory structure:

.
├── doc-Administration_Guide
│   ├── master.adoc
│   ├── part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc
│   ├── common -> ../common
├── common
│   ├── collateral_files
│   │   ├── ovirt-attributes.adoc
│   │   └── rhv-attributes.adoc
...

Abbreviated AsciiDoc files:

$ cat doc-Administration_Guide/master.adoc
= Administration Guide
include::common/collateral_files/rhv-attributes.adoc[]
include::part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc[]

$ cat doc-Administration_Guide/common/collateral_files/rhv-attributes.adoc
:vernum_rhv: 4.3
:URL_customer-portal: https://access.redhat.com/
:URL_docs: documentation/
:URL_lang-locale: en-us/
:URL_product_rhv: red_hat_virtualization/
:URL_vernum_rhv: {vernum_rhv}/
:URL_virt_product_docs: {URL_customer-portal}{URL_docs}{URL_lang-locale}{URL_product_rhv}{URL_vernum_rhv}

$ cat doc-Administration_Guide/part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc
...
* Managing searches saved as link:{URL_virt_product_docs}html-single/introduction_to_the_administration_portal/index#chap-Bookmarks[public bookmarks].

Example output

The following output is generated by using the standard output mode.

$ echo doc-Administration_Guide/master.adoc | asciidoc-aware-link-check --stdin
[I] Loading doc-Administration_Guide/master.adoc
Checking... [=========================] 100%
...
[✖] https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.3/html-single/introduction_to_the_administration_portal/index (.../rhev-docs/doc-Administration_Guide/part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc:13)
[✓] https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.3/html-single/virtual_machine_management_guide/
[✖] https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.3/html/data_warehouse_guide/chapter-1-installing-and-configuring-data-warehouse (.../rhev-docs/doc-Administration_Guide/chap-Dashboard.adoc:14)
...

Example output (CSV)

The following output is generated by using CSV mode. The output lists only broken links. This mode is suitable for large doc sets where the output might be part of a pipeline of other commands or pasted into a spreadsheet.

$ echo doc-Administration_Guide/master.adoc | asciidoc-aware-link-check --csv --stdin
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.3/html-single/introduction_to_the_administration_portal/index,.../rhev-docs/doc-Administration_Guide/part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc,13
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.3/html/data_warehouse_guide/chapter-1-installing-and-configuring-data-warehouse,.../rhev-docs/doc-Administration_Guide/chap-Dashboard.adoc,14
https://github.com/OpenAttestation/OpenAttestation/wiki,.../rhev-docs/doc-Administration_Guide/chap-Pools.adoc,45

Known issues

A HTTP/1.1 301 Moved Permanently is considered a broken link.
Any links within a listing block are ignored.