lintAsciiDoc

About This Task

This task runs the docToolchain AsciiDoc Linter over your AsciiDoc sources to keep them clean and consistent. It checks rules for heading structure, formatting, whitespace and image usage, and reports any problems it finds.

Setup and Configuration

The linter is a Python tool. If the asciidoc-linter command is not on your PATH, the task prints how to install it (with uv or pip) and stops — no stack trace:

uv tool install git+https://github.com/docToolchain/asciidoc-linter

Then run the task:

./dtcw4 local lintAsciiDoc

By default the task lints the AsciiDoc entries from your inputFiles. You can configure it in docToolchainConfig.groovy:

lintAsciiDoc = [
    // Fail the build when the linter reports problems (default: false — warn only)
    failOnError : false,
    // Output format: 'console' (default, human-readable) or 'json'
    format      : 'console',
    // Optional: explicit files/paths to lint (relative to inputPath).
    // When set, these replace the inputFiles selection.
    files       : ['arc42/arc42.adoc'],
]

Exit Behaviour

Situation Result

No problems found

Task succeeds (exit 0)

Problems found, failOnError is false (default)

Problems are printed, task still succeeds — safe to add to an existing pipeline first

Problems found, failOnError is true

Task fails (non-zero exit) so CI blocks the change

Linter not installed

Actionable install hint, task exits non-zero

Further Reading and Resources

Source

View the source of this task: scripts/lintAsciiDoc.groovy on GitHub