AsciiDoc Linter

License: MIT Python Version

A Python-based linter for AsciiDoc files that helps maintain consistent documentation quality and style. Part of the docToolchain project.

About

AsciiDoc Linter is a command-line tool that checks your AsciiDoc files for common issues and style violations. It helps maintain consistent documentation by enforcing rules for heading structure, formatting, whitespace, and image usage.

This project is part of docToolchain (https://doctoolchain.org), a collection of documentation tools and best practices.

Features

Implemented Rules

Rule ID Description Severity

HEAD001

Check for proper heading hierarchy (no skipping levels)

ERROR

HEAD002

Verify heading format (spacing and capitalization)

ERROR/WARNING

HEAD003

Detect multiple top-level headers

ERROR

BLOCK001

Check for unterminated blocks (listing, example, sidebar, etc.)

ERROR

BLOCK002

Verify proper spacing around blocks

WARNING

WS001

Check whitespace usage (blank lines, list markers, tabs)

WARNING

IMG001

Verify image attributes and file references

WARNING/ERROR

Planned Rules

  • TABLE001: Table formatting consistency

  • LINK001: Broken internal references

  • FMT001: Markdown-compatible styles detection

Installation

# Clone the repository
git clone https://github.com/docToolchain/asciidoc-linter.git

# Navigate to the project directory
cd asciidoc-linter

# Install the package
pip install .

Usage

Basic Usage

# Check a single file
asciidoc-lint document.adoc

# Check multiple files
asciidoc-lint doc1.adoc doc2.adoc

# Check with specific output format
asciidoc-lint --format json document.adoc

Output Formats

The linter supports three output formats:

  • console (default): Human-readable output

  • json: Machine-readable JSON format

  • html: HTML report format

Example Output

Checking file: document.adoc

ERROR: Heading level skipped: found h3 after h1 (line 15)
  === Advanced Topics

WARNING: Heading should start with uppercase letter (line 23)
  == introduction to concepts

ERROR: Unterminated listing block starting (line 45)
  ----

WARNING: Block should be preceded by a blank line (line 67)
  ----

ERROR: Multiple top-level headings found (line 30)
  First heading at line 1: 'Document Title'

WARNING: Missing alt text for image: diagram.png (line 80)
  image::diagram.png[]

Development

Running Tests

# Run all tests
python run_tests.py

# Run specific test file
python -m unittest tests/rules/test_heading_rules.py

Project Structure

asciidoc-linter/
├── asciidoc_linter/
│   ├── __init__.py
│   ├── cli.py
│   ├── rules/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── heading_rules.py
│   │   ├── block_rules.py
│   │   ├── whitespace_rules.py
│   │   └── image_rules.py
│   ├── parser.py
│   └── reporter.py
├── tests/
│   └── rules/
│       ├── test_heading_rules.py
│       ├── test_block_rules.py
│       ├── test_whitespace_rules.py
│       └── test_image_rules.py
├── docs/
│   ├── requirements.adoc
│   └── block_rules.adoc
├── README.adoc
└── run_tests.py

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Guidelines

  1. Write tests for new rules

  2. Update documentation

  3. Follow Python code style guidelines

  4. Add appropriate error messages and context

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Part of the docToolchain project (https://doctoolchain.org)

  • Inspired by various linting tools and the need for better AsciiDoc quality control

  • Thanks to the AsciiDoc community for their excellent documentation and tools

Roadmap

  1. Phase 1 (Current)

    • ✅ Basic heading rules

    • ✅ Block structure rules

    • ✅ Whitespace rules

    • ✅ Image validation

    • ⏳ Configuration system

  2. Phase 2

    • 🔲 Table validation

    • 🔲 Link checking

    • 🔲 Format rules

  3. Phase 3

    • 🔲 IDE integration

    • 🔲 Git pre-commit hooks

    • 🔲 Custom rule development

Contact