README.adoc - Project documentation

Table of Contents

• About
• Features
  • Implemented Rules
  • Planned Rules
• Installation
• Usage
  • Basic Usage
  • Output Formats
  • Example Output
• Development
  • Current Status
  • Running Tests
  • Project Structure
• Contributing
  • Development Guidelines
• License
• Acknowledgments
• Roadmap
• Contact

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.

Note	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

• Project Homepage: https://github.com/docToolchain/asciidoc-linter

• Issue Tracker: https://github.com/docToolchain/asciidoc-linter/issues

• docToolchain Homepage: https://doctoolchain.org