markdown-linter-fixer

# Markdown Linter Fixer

## Overview

Systematically fix linting issues in `*.md` files using markdownlint-cli2 through a structured workflow that diagnoses, fixes automatically where possible, and guides manual fixes when needed.

## When to Use This Skill

Use this skill when:

- Fixing markdown linting errors in projects
- Standardizing markdown formatting across multiple files
- Addressing ordered list numbering issues (MD029)
- Preparing markdown documentation for quality standards
- Setting up markdown linting for the first time in a project

## Workflow Process

### Phase 1: Environment Setup & Prerequisites

#### Verify markdownlint-cli2 Installation

Check if markdownlint-cli2 is installed:

```bash
markdownlint-cli2 --version
```

If missing, install it globally via npm:

```bash
npm install -g markdownlint-cli2
```

Handle any permission or installation errors by suggesting:

- Local installation: `npm install --save-dev markdownlint-cli2`
- Using npx: `npx markdownlint-cli2`
- User-specific npm directory configuration

#### Configuration File Check

Look for existing markdown configuration files in the project root:

- `.markdownlint-cli2.jsonc`
- `.markdownlint.json`
- `.markdownlint.yaml`
- `.markdownlint.yml`
- `.markdownlintrc`

If none exist, create `.markdownlint-cli2.jsonc` with:

```json
{
  "config": {
    "MD013": false
  },
  "ignores": []
}
```

This disables max line length warnings while keeping other rules active. The `ignores` array can be used to exclude specific files from linting (e.g., example files with intentional errors).

**IMPORTANT - Configuration Policy**:

- **Do not ignore/hide linting errors** by modifying `.markdownlint-cli2.jsonc`
- **Only modify the `ignores` array** based on:
  - Explicit user input or approval
  - Content from `.gitignore` file (files already ignored by git)
- **Always ask the user** before adding files to the ignore list
- **Never suppress errors** without user consent - fix them instead

### Phase 2: