AsciiDoc Linter

Fact Sheet

AsciiDoc Linter is a powerful and configurable validation tool for AsciiDoc documents, designed to ensure document quality and consistency across your documentation projects.

Key Features

• 15 Block Type Validators - Validates admonitions, code blocks, tables, images, lists, and more

• Configurable Rules - YAML-based configuration with JSON Schema validation

• Multiple Output Formats - Console (with syntax highlighting) and JSON reporting

• CI/CD Ready - Exit codes based on severity levels for pipeline integration

• Extensible Architecture - Easy to add custom validators and rules

• Performance Optimized - Pattern caching and efficient file processing

Supported Validations

Validation Type	Description
Structure Validation	Document hierarchy, section ordering, metadata requirements
Block Validation	Block types, ordering, occurrences, and content rules
Pattern Validation	Regex-based content validation for text patterns
Attribute Validation	Document and block attribute requirements
Length Validation	Min/max length constraints for content

Quick Start

# Install from Maven Central
mvn dependency:get -Dartifact=com.dataliquid:asciidoc-linter:0.1.0

# Run with default configuration
java -jar asciidoc-linter.jar -i "**/*.adoc"

# Run with custom rules
java -jar asciidoc-linter.jar -i "docs/**/*.adoc" -c my-rules.yaml

Overview

AsciiDoc Linter provides comprehensive validation for AsciiDoc documents, helping teams maintain consistent documentation standards. It supports complex validation scenarios including:

• Enforcing document structure and hierarchy

• Validating required metadata and attributes

• Ensuring consistent use of AsciiDoc blocks

• Pattern matching for terminology and style guides

• Integration with CI/CD pipelines for automated checks

The linter processes AsciiDoc files using AsciidoctorJ and applies configurable validation rules, making it suitable for projects ranging from small documentation sets to large-scale technical documentation systems.

Prerequisites

• Java 17 or higher

• Maven 3.8 or higher (for building from source)

Usage

Command Line Interface

# Basic usage
java -jar asciidoc-linter.jar -i "**/*.adoc"

# With custom configuration
java -jar asciidoc-linter.jar -i "docs/**/*.adoc" -c .linter-config.yaml

# JSON output for CI/CD
java -jar asciidoc-linter.jar -i "**/*.adoc" -f json -o report.json

# Generate documentation for your configuration
java -jar asciidoc-linter.jar -c my-rules.yaml --generate-docs

Configuration Example

document:
  metadata:
    attributes:
      - name: author
        required: true
        severity: error
      - name: version
        required: true
        pattern: "^v?\\d+\\.\\d+\\.\\d+$"
        severity: error

  sections:
    - name: introduction
      level: 1
      min: 1
      max: 1
      title:
        pattern: "^Introduction$"
        severity: error
      allowedBlocks:
        - paragraph:
            severity: warn
            occurrence:
              min: 1
              max: 3
            lines:
              min: 3
              max: 20
        - listing:
            severity: error
            language:
              required: true
              allowed: ["java", "python", "yaml"]

License

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