README.adoc - Project documentation

AsciiDoc Linter

License: MIT Python Version Test Coverage Test Success Rate

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 Status

HEAD001

Check for proper heading hierarchy (no skipping levels)

ERROR

✅ Stable

HEAD002

Verify heading format (spacing and capitalization)

ERROR/WARNING

✅ Stable

HEAD003

Detect multiple top-level headers

ERROR

✅ Stable

BLOCK001

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

ERROR

✅ Stable

BLOCK002

Verify proper spacing around blocks

WARNING

✅ Stable

WS001

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

WARNING

✅ Stable

IMG001

Verify image attributes and file references

WARNING/ERROR

✅ Stable

TABLE001

Table formatting consistency

WARNING/ERROR

⚠️ Beta

Planned Rules

  • TABLE002: Table content validation

  • 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

Current Status

  • Test Coverage: 95%

  • Test Success Rate: 97.3% (107/110 tests passing)

  • Known Issues:

    • Table content validation needs improvement

    • Rules.py requires test coverage

    • Reporter module needs additional tests

Running Tests

# Run all tests
python run_tests.py

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

# Run tests with coverage
python run_tests_html.py

Project Structure

asciidoc-linter/
├── asciidoc_linter/
│   ├── __init__.py
│   ├── cli.py
│   ├── linter.py
│   ├── parser.py
│   ├── reporter.py
│   └── rules/
│       ├── __init__.py
│       ├── base.py
│       ├── base_rules.py
│       ├── block_rules.py
│       ├── heading_rules.py
│       ├── image_rules.py
│       ├── table_rules.py
│       └── whitespace_rules.py
├── tests/
│   ├── __init__.py
│   ├── test_base.py
│   ├── test_cli.py
│   ├── test_linter.py
│   ├── test_reporter.py
│   └── rules/
│       ├── test_block_rules.py
│       ├── test_heading_rules.py
│       ├── test_image_rules.py
│       ├── test_table_rules.py
│       └── test_whitespace_rules.py
├── docs/
│   ├── arc42/
│   ├── manual/
│   ├── test-results/
│   ├── requirements.adoc
│   └── implementation_plan.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

  5. Ensure test coverage remains above 90%

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

    • ⚠️ Table validation

    • ⏳ Configuration system

  2. Phase 2 (Next)

    • 🔲 Fix table content validation

    • 🔲 Improve test coverage

    • 🔲 Add link checking

    • 🔲 Add format rules

  3. Phase 3 (Future)

    • 🔲 IDE integration

    • 🔲 Git pre-commit hooks

    • 🔲 Custom rule development

    • 🔲 Performance optimization

Contact