markdown-linter

# Markdown Linter

## What This Does

A CLI tool to lint Markdown files for common formatting issues, style consistency, and broken links. Helps maintain documentation quality by catching errors before publication.

Key features:
- **Header hierarchy validation** - ensure proper nesting (no skipped levels)
- **Image alt text checking** - flag images without descriptive alt text
- **Internal link validation** - check that internal links (within same doc) point to existing anchors
- **Line length checking** - warn about lines exceeding configurable length (default 80 chars)
- **Trailing whitespace detection** - find and report trailing spaces/tabs
- **List consistency** - ensure consistent list markers (-, *, +) within same document
- **Code block language** - recommend adding language specification to code blocks
- **Empty link detection** - flag links with empty text or URLs
- **Duplicate headers** - warn about duplicate header text within same file
- **External link checking** - optionally validate external URLs (requires network)

## How To Use

Run the skill with:
```bash
./scripts/main.py run --input path/to/file.md
```

Or lint multiple files:
```bash
./scripts/main.py run --input "*.md"
```

### Options

- `--input`: Path to Markdown file(s) (supports glob patterns)
- `--max-line-length`: Maximum allowed line length (default: 80)
- `--check-external-links`: Enable external URL validation (default: false)
- `--ignore-rules`: Comma-separated list of rule IDs to ignore

### Output

Returns JSON with linting results:
```json
{
  "file": "example.md",
  "issues": [
    {
      "line": 10,
      "column": 1,
      "rule": "MD001",
      "severity": "warning",
      "message": "Header levels should only increment by one level at a time",
      "fix": "Change ## to #"
    }
  ],
  "summary": {
    "total_issues": 5,
    "errors": 2,
    "warnings": 3
  }
}
```

## Limitations

- External link checking requires network connectivity and may be slow
- Readability scores...

# Markdown Linter

A CLI tool to lint Markdown files for formatting issues, broken links, and style consistency.

## Quick Start

```bash
# Lint a single file
./scripts/main.py run --input README.md

# Lint multiple files
./scripts/main.py run --input "docs/*.md"
```

## Installation

This skill is installed via OpenClaw. Once installed, you can use it directly from your OpenClaw agent.

## Features

- **Header hierarchy validation**
- **Image alt text checking**
- **Internal link validation**
- **Line length checking**
- **Trailing whitespace detection**
- **List consistency checking**
- **Code block language recommendation**
- **Empty link detection**
- **Duplicate header warnings**
- **External link checking** (optional)

## Configuration

Customize linting behavior with command-line options:

- `--max-line-length`: Set maximum line length (default: 80)
- `--check-external-links`: Enable external URL validation
- `--ignore-rules`: Comma-separated list of rule IDs to ignore

## Output

The tool outputs JSON with detailed issue reports, including line numbers, severity levels, and suggested fixes.

## Contributing

Issues and pull requests welcome. See the source code in `scripts/main.py`.

## License

MIT