Skip to content
Yet another developer blog


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.


  • Nodejs >= 10


To install the application, enter the following command:

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


To learn about supported options, enter the following command:

$ asciidoc-aware-link-check --help
Usage: asciidoc-aware-link-check [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


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
$ cat doc-Administration_Guide/common/collateral_files/rhv-attributes.adoc
:vernum_rhv: 4.3
: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%
[✖] (.../rhev-docs/doc-Administration_Guide/part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc:13)
[✖] (.../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,.../rhev-docs/doc-Administration_Guide/part-Administering_and_Maintaining_the_Red_Hat_Virtualization_Environment.adoc,13,.../rhev-docs/doc-Administration_Guide/chap-Dashboard.adoc,14,.../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.