Usage Guide

Command Line Interface

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

# Use specific configuration
asciidoc-linter --config my-config.yml document.adoc

# Enable verbose output
asciidoc-linter --verbose document.adoc

# Enable debug output
asciidoc-linter --debug document.adoc

Command Line Options

Option Default Description

--format

console

Output format (console, json, html)

--config

None

Path to configuration file

--verbose

False

Enable verbose output

--debug

False

Enable debug output

--quiet

False

Suppress non-error output

Configuration

Configuration File

# .asciidoc-lint.yml
rules:
  HEAD001:
    enabled: true
    severity: error
  HEAD002:
    enabled: true
    severity: warning
  WS001:
    enabled: false
    severity: warning

Rule Configuration

  • Enable/disable rules

  • Set severity levels

  • Configure rule-specific options

  • Set file patterns

Output Formats

Console Output

document.adoc:15 ERROR: Heading level skipped
document.adoc:23 WARNING: Heading should start with uppercase

JSON Output

{
  "findings": [
    {
      "rule": "HEAD001",
      "severity": "error",
      "message": "Heading level skipped",
      "line": 15
    }
  ]
}

HTML Report

Generates a detailed HTML report with:

  • Summary statistics

  • Detailed findings

  • Source context

  • Rule explanations

Integration

Git Pre-commit Hook

#!/bin/sh
files=$(git diff --cached --name-only --diff-filter=ACM | grep '.adoc$')
if [ -n "$files" ]; then
    asciidoc-linter $files
fi

CI/CD Integration

GitHub Actions Example
name: Lint AsciiDoc
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Lint Documentation
        run: |
          pip install asciidoc-linter
          asciidoc-linter docs/

Best Practices

Document Organization

  • Use consistent heading levels

  • Add blank lines around blocks

  • Use proper formatting

  • Include alt text for images

Error Resolution

Table 1. Common Issues and Solutions
Issue Solution

Skipped heading level

Ensure heading levels increment by one

Missing space after =

Add space after heading markers

Multiple top-level headings

Use only one level-1 heading per document

Troubleshooting

Common Problems

  • Configuration file not found

  • Rule conflicts

  • Performance issues

  • False positives

Debug Mode

# Enable debug output
asciidoc-linter --debug document.adoc

# Show rule processing details
asciidoc-linter --verbose document.adoc