asciidoctor-lint — in-house AsciiDoc linter

On this page

Overview

asciidoctor-lint is an in-house linter for the Antora .adoc sources (CHANGELOG, plans, ADRs, runbooks). It catches render bugs (broken inline formatting, duplicate auto-IDs) and style warnings. It is advisory — not wired into cargo xtask validate — and several of its rule families are high-false-positive, so verify findings against the rendered HTML before chasing them.

Location

Binary

/home/bitskrieg/code/cargo-target/debug/asciidoctor-lint (the workspace cargo-target is shared across canopy sibling projects; it is not under canopy’s own target/)

Source

~/code/asciidoctor-lint (sibling repo — read the rule implementation when verifying a suspected false positive)

If the binary is absent, build it from the source repo (cargo build in ~/code/asciidoctor-lint).

Usage

asciidoctor-lint CHANGELOG.adoc                          # lint one file
asciidoctor-lint --rule ASD005,ASD009 docs/.../file.adoc # specific rules only
asciidoctor-lint --fix --dry-run path.adoc               # preview auto-fixes
asciidoctor-lint --best-practices path.adoc              # add the BP-family rules

Rule families and false-positive risk

Rule Severity Typical cause False-positive risk

ASD005

Error

Duplicate auto-ID from a repeated section header (e.g. === Added under every version)

Inherent to the Keep-a-Changelog format; not a render bug

ASD009

Warning

Possible unclosed ** / __ inline formatting

High — fires inside ... passthroughs where formatting is already disabled

ASD014

Warning

Undefined attribute reference {name}

Moderate — {…​} placeholders in body text render literally anyway

ASD025

Info

Missing :description: (SEO)

Style, not a bug

INL010

Warning

Constrained …​ may not render

Very high — fires on identifier-like prose such as check_time_limit() where there is no real render bug

Triage heuristic

The linter flags more than raw asciidoctor rendering actually breaks on. Confirm a render impact before fixing:

asciidoctor file.adoc -o /tmp/check.html
grep -c '<mark>' /tmp/check.html                                           # >0 means a #...# collision
grep -oE '<code>[^<]*<em>[^<]*</em>[^<]*</code>' /tmp/check.html | wc -l    # >0 means underscores broke a code span
grep -oE '<code>[^<]*<strong>[^<]*</strong>[^<]*</code>' /tmp/check.html | wc -l
grep -c '<div class="literalblock">' /tmp/check.html                       # >0 means indented Markdown sub-bullets

If those counts are zero, ASD009 / INL010 warnings on the same file are almost certainly false positives — the passthrough or surrounding context already prevented the render bug the heuristic suspected. Don’t fix them mechanically.

Filing a linter bug

If the rendered HTML is demonstrably clean and the linter still flags it, that’s a false positive. Read the rule under ~/code/asciidoctor-lint/, then either tighten the rule or record the exception in a repo-root .asciidoctor-lint.toml (none exists in canopy yet; it would land at the repo root when first needed).

Related

  • Developer Guide — project docs are AsciiDoc (Antora), not Markdown.

  • xtask catalog — cargo xtask docs plan-lint is the blocking ADR-013 plan-status lint (separate from this advisory tool).

Edit this page · default