Link Search Menu Expand Document

asciidoc-aware-link-check

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

Table of contents

  1. Intended usage
  2. Prerequisites
  3. Installation
  4. Usage
  5. Examples
    1. Example documentation set
    2. Example output
    3. Example output (CSV)
  6. Known issues

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 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] ASSEMBLY_FILE

Options:
  --no-progress  Hide progress bar.
  -q, --quiet    Display errors only.
  --csv          Output to stdout in CSV format. Outputs BROKEN_LINK,MODULE,LINE_NUM. This option implies --no-progress and --quiet.
  -n, --dry      Dry run.
  --asciibinder  Support asciibinder style include directives.
  -h, --help     output usage information

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.

$ asciidoc-aware-link-check <ASSEMBLY_FILE>

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' | \
  xargs -L1 -I% -P1 asciidoc-aware-link-check %

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.

$ asciidoc-aware-link-check doc-Administration_Guide/master.adoc
[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.

$ asciidoc-aware-link-check --csv doc-Administration_Guide/master.adoc
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.