AsciiDoc Linter

Table of Contents

• About
• Features
  • Implemented Rules
  • Planned Rules
• Installation
• Usage
  • Basic Usage
  • Output Formats
  • Example Output
• Development
  • 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
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

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

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

• docToolchain Homepage: https://doctoolchain.org