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

FMT001

Detect explicit numbered lists (1., 2., etc.) instead of AsciiDoc dot-syntax

WARNING

✅ Stable

FMT002

Detect non-semantic definition list patterns (Term: instead of Term::)

WARNING

✅ Stable

FMT003

Detect counter syntax in section titles (1)

WARNING

✅ Stable

FMT004

Detect Markdown syntax in AsciiDoc files (headings, links, images, code blocks)

WARNING

✅ Stable

Planned Rules

  • TABLE002: Table content validation

  • LINK001: Broken internal references

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-linter document.adoc

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

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

Output Formats

The linter supports three output formats:

  • console (default): Human-readable output with color

  • plain: Human-readable output without color

  • 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[]

Using with Docker

You can run the AsciiDoc Linter in a Docker container without installing Python locally.

Build the Docker image

docker build -t asciidoc-linter .

Run the linter

docker run --rm -v $(pwd):/docs asciidoc-linter document.adoc

Replace document.adoc with the path to the AsciiDoc file you want to lint. The -v $(pwd):/docs option mounts the current directory to /docs inside the container.

Using as a GitHub Action

You can automatically lint your AsciiDoc files on every push or pull request by adding a workflow file.

Create .github/workflows/asciidoc-linter.yml:

name: AsciiDoc Linter

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t asciidoc-linter .

      - name: Run AsciiDoc Linter
        run: |
          for file in $(find . -name "*.adoc" -type f); do
            docker run --rm -v ${{ github.workspace }}:/docs asciidoc-linter "$file"
          done

Development

Current Status

  • Test Coverage: 95%

  • Test Success Rate: 100% (216/216 tests passing)

  • Known Issues:

    • Table content validation needs improvement

Running Tests

# Run all tests
python -m pytest

# Run specific test file
python -m pytest 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
│       ├── format_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_format_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

Phase 1 (Current)

  • ✅ Basic heading rules

  • ✅ Block structure rules

  • ✅ Whitespace rules

  • ✅ Image validation

  • ⚠️ Table validation

  • ⏳ Configuration system

Phase 2 (Next)

  • 🔲 Fix table content validation

  • 🔲 Improve test coverage

  • 🔲 Add link checking

  • ✅ Add format rules (FMT001-FMT004)

Phase 3 (Future)

  • 🔲 IDE integration

  • 🔲 Git pre-commit hooks

  • 🔲 Custom rule development

  • 🔲 Performance optimization

Contact