Skip to main content
Linkspector provides comprehensive support for AsciiDoc files, checking not only HTTP/HTTPS URLs but also internal anchors, cross-references, and local file links. Linkspector extracts and validates all AsciiDoc hyperlink types:

Direct URLs

Auto-detected HTTP/HTTPS links

Link Macros

link: macro syntax

Anchors

Four types of anchor definitions

Cross-References

Internal and external references

​
URL Formats

​
Direct URLs

AsciiDoc automatically detects and converts URLs: 
https://example.com
http://docs.example.com/guide
Linkspector validates these URLs by:
  • Checking HTTP status codes
  • Following redirects (configurable)
  • Using Puppeteer for JavaScript-rendered sites
The link: macro provides explicit link syntax: 
link:https://example.com[Visit Example]
link:https://api.example.com/docs[API Documentation]
Linkspector validates both the URL and local file paths in link macros.

​
Anchor Definitions

AsciiDoc supports four types of anchor definitions. Linkspector extracts all types for validation.

​
1. Block Anchors

Standard anchor syntax using double brackets: 
[[introduction]]
== Introduction

This section introduces the topic.

[[config-options, Configuration Options]]
== Configuration
Extracted data:
  • ID: introduction, config-options
  • Description: null, Configuration Options
  • Type: block

​
2. Bibliography Anchors

Used in lists for bibliographic references: 
* [[[citation-key]]] Author Name. Book Title. 2024.
* [[[rfc2616, RFC 2616]]] HTTP/1.1 Specification
Bibliography anchors ([[[...]]]) must appear in list items (lines starting with * or -).
Extracted data:
  • ID: citation-key, rfc2616
  • Description: null, RFC 2616
  • Type: bibliography

​
3. Inline Anchors

Concise syntax using hash symbol: 
[#section-overview]
This paragraph has an anchor.

[#important-note]
NOTE: This is an important note with an anchor.
Extracted data:
  • ID: section-overview, important-note
  • Type: inline

​
4. Anchor Macros

Inline anchor placement: 
This paragraph contains an anchor:target-location[] in the middle of the text.

You can also use anchor:another-anchor[visible text] with text.
Extracted data:
  • ID: target-location, another-anchor
  • Text: null, visible text
  • Type: macro

​
Cross-References

Linkspector validates that cross-references point to existing anchors.

​
Internal References (Shorthand)

Reference anchors within the same document: 
[[introduction]]
== Introduction

Welcome to our documentation.

== Getting Started

Refer to the <<introduction>> section for background.

See <<introduction, Introduction chapter>> for details.
Validation:
  • Linkspector checks that introduction anchor exists
  • Reports error if anchor is not defined
  • Detects duplicate anchor definitions

​
External References (XRef Shorthand)

Reference anchors in other AsciiDoc files: 
See <<other-file.adoc#section-name>> for more details.

Refer to <<guide.adoc#installation, installation guide>>.
Validation:
  • Checks that other-file.adoc and guide.adoc exist
  • Verifies that referenced anchors (section-name, installation) are defined in those files
  • Reports missing files or missing anchors
Linkspector auto-corrects missing .adoc extensions: <<file#anchor>> becomes <<file.adoc#anchor>>.

​
XRef Macros

Explicit cross-reference syntax: 
[[overview]]
== Overview

Content here.

== Details

See the xref:overview[overview section] above.

Refer to xref:other-doc.adoc#config[configuration guide].
Internal reference: 
xref:overview[overview section]
External reference: 
xref:other-doc.adoc#config[configuration guide]
Validation:
  • Internal: Checks anchor exists in current file
  • External: Validates file existence and anchor presence
The link: macro can reference local files: 
Download the link:files/sample.pdf[PDF guide].

See our link:../README.adoc[README file].

View the link:assets/diagram.png[architecture diagram].
Validation:
  • Linkspector checks file existence relative to the current document
  • Reports missing files
  • Handles HTML fragment syntax: link:file.html#section[text]
HTML fragments are dropped during validation: file.html#section → checks file.html

​
Comment Handling

Linkspector correctly ignores links and anchors in comments:

​
Single-line Comments

// This is a comment with a link: https://example.com
// [[commented-anchor]]

​
Multi-line Comment Blocks

////
This entire block is commented out.

https://ignored-link.com
[[ignored-anchor]]
xref:ignored-reference[]
////
Behavior:
  • All content between //// delimiters is ignored
  • Single-line comments starting with // are skipped
  • No validation errors for links/anchors in comments

​
Reference Validation

Linkspector provides specialized validation utilities for AsciiDoc references.

​
Internal Reference Validation

1

Extract anchors

All anchor types are extracted from the document:
  • Block anchors ([[...]])
  • Bibliography anchors ([[[...]]])
  • Inline anchors ([#...])
  • Anchor macros (anchor:...[])
2

Extract internal references

Cross-references without file paths:
  • <<anchor>>
  • <<anchor, text>>
  • xref:anchor[text]
3

Validate references

Each internal reference is checked against available anchors.Error reported if:
  • Reference points to non-existent anchor
  • Duplicate anchors exist

​
External Reference Validation

1

Extract external references

Cross-references with file paths:
  • <<file.adoc#anchor>>
  • xref:file.adoc#anchor[text]
2

Resolve file paths

File paths are resolved relative to the current document’s directory.
3

Validate file existence

Linkspector checks if the referenced file exists.Error if: File not found
4

Validate anchor existence

If an anchor is specified, Linkspector:
  • Reads the target file
  • Searches for the anchor definition
  • Reports error if anchor not found

​
Configuration

Enable AsciiDoc support by including file extensions in your configuration:
.linkspector.yml
fileExtensions:
  - md
  - adoc
  - asciidoc
  - asc

dirs:
  - ./docs
  - ./guides

useGitIgnore: true

aliveStatusCodes:
  - 200
  - 201
  - 204
By default, Linkspector only checks .md files. You must explicitly enable AsciiDoc extensions.

​
Complete Example

Here’s a comprehensive AsciiDoc file demonstrating all link types:
example.adoc
= Documentation Guide
:author: Documentation Team

// This comment contains https://ignored-link.com which won't be checked

[[introduction]]
== Introduction

Welcome to the guide. Visit our website at https://example.com.

For more information, see link:https://docs.example.com[our documentation].

[[installation]]
== Installation

Download the link:files/installer.zip[installer package].

[#quick-start]
== Quick Start

Refer back to the <<introduction>> for context.

See the <<installation, installation section>> to get started.

== Advanced Topics

For configuration details, see xref:config.adoc#options[configuration options].

Refer to <<advanced-guide.adoc#troubleshooting>> for help.

== References

* [[[api-spec, API Specification]]] Internal API Documentation
* [[[rfc2616]]] HTTP/1.1 Protocol

Citing: As described in <<api-spec>>, the API follows REST principles.

== Notes

This paragraph has an anchor:key-point[] right here.

Refer to the anchor:key-point[key point] mentioned earlier.

////
Commented out section

https://not-checked.com
[[commented-anchor]]
<<commented-reference>>
////
What Linkspector validates: 
https://example.com → HTTP check
https://docs.example.com → HTTP check

​
Error Messages

Linkspector provides clear error messages for AsciiDoc validation failures:

​
Missing Internal Anchor

example.adoc:23:1: Cannot find anchor: 'missing-anchor' in current document.

​
Duplicate Anchor

example.adoc:45:1: Duplicate anchor found: 'introduction'. First defined at line 12.

​
Missing External File

example.adoc:34:1: Cannot find referenced file: 'config.adoc'

​
Missing Anchor in External File

example.adoc:56:1: Cannot find anchor 'options' in file 'config.adoc'

​
Broken URL

example.adoc:15:30: 🚫 https://broken-link.com Status:404 Not Found

​
Best Practices

Choose meaningful anchor names:
// Good
[[installation-prerequisites]]
[[config-database-options]]

// Avoid
[[section1]]
[[a1]]
Linkspector detects duplicate anchors and reports them as errors. Use unique IDs throughout your documentation.
Reference files relative to the current document:
link:../assets/diagram.png[diagram]
xref:../guides/installation.adoc[installation]
Always specify .adoc extensions in cross-references:
// Good
xref:config.adoc#options[]

// Works but less clear
xref:config#options[]
When reorganizing documentation, run Linkspector to catch broken references:
linkspector check -s

​
Implementation Details

Linkspector’s AsciiDoc parser is located in:
  • lib/extract-asciidoc-comprehensive.js - Link and reference extraction
  • lib/validate-asciidoc-references.js - Validation utilities

​
Extracted Reference Data

The parser provides structured data for validation: 
{
  anchors: [],         // All anchor definitions
  internalRefs: [],    // References within current file
  externalRefs: [],    // References to other files
  externalUrls: [],    // HTTP/HTTPS URLs
  localFiles: []       // Local file references
}

​
Validation Workflow

1

Parse AsciiDoc

Extract all links, anchors, and references
2

Validate internal references

Check cross-references against available anchors
3

Validate external references

Verify file existence and anchor presence
4

Validate URLs

Check HTTP/HTTPS links using Puppeteer
5

Report results

Output errors in console or RDJSON format

​
Limitations

  • Include directives: Currently not resolved. External includes are not parsed.
  • Conditional blocks: Content in ifdef/ifndef blocks is always parsed.
  • Preprocessor directives: Attributes and substitutions are not evaluated.
  • Inter-document attributes: Cross-file attribute references are not validated.

​
Troubleshooting

Ensure anchors use correct syntax:
  • [[id]] or [[id, description]] for block anchors
  • [#id] for inline anchors
  • anchor:id[] for anchor macros
Verify:
  1. File paths are relative to the current document
  2. File extensions are included (.adoc)
  3. Referenced files exist in the repository
Ensure comments use proper syntax:
  • Single line: // comment
  • Multi-line: //// delimiters on separate lines
Bibliography anchors must be in list items:
// Works
* [[[ref1]]] Citation text

// Doesn't work
[[[ref2]]] Citation text

​
Next Steps

CI/CD Integration

Automate AsciiDoc link checking in CI/CD

GitHub Actions

Check AsciiDoc files in GitHub workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us