markdown-linter-fixer

What this skill does

# Markdown Linter Fixer

## Contents

- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Workflow Process](#workflow-process)
  - [Phase 1: Environment Setup & Prerequisites](#phase-1-environment-setup--prerequisites)
  - [Phase 2: Diagnostic Assessment](#phase-2-diagnostic-assessment)
  - [Phase 3: Issue Analysis](#phase-3-issue-analysis)
  - [Phase 4: Automatic Fixes](#phase-4-automatic-fixes)
  - [Phase 5: Manual Fixes](#phase-5-manual-fixes)
  - [Phase 6: Verification & Reporting](#phase-6-verification--reporting)
- [Quick Reference Checklist](#quick-reference-checklist)
- [Key Principles](#key-principles)
- [Common Scenarios](#common-scenarios)
- [Resources](#resources)

## 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: Diagnostic Assessment

#### Initial Root-Level Scan

Run linter on root-level markdown files:

```bash
markdownlint-cli2 "*.md"
```

Document all issues found, including:

- Error codes (e.g., MD029, MD001, MD032)
- File names and line numbers
- Brief description of each issue

#### Comprehensive Recursive Scan

Scan all markdown files including subdirectories:

```bash
markdownlint-cli2 "**/*.md"
```

This includes files in directories like:

- `docs/`
- `guides/`
- Any other subdirectories containing markdown

Create a complete inventory of all issues across the project.

### Phase 3: Issue Analysis

#### Categorize Errors by Type

Group all identified linting errors by error code:

- Track frequency of each error type
- Identify which errors are auto-fixable
- Flag special attention areas (especially MD029, which often requires understanding indentation issues)

Common error types:

- **MD001**: Heading levels should increment by one level at a time
- **MD009**: Trailing spaces
- **MD010**: Hard tabs
- **MD012**: Multiple consecutive blank lines
- **MD029**: Ordered list item prefix (requires special attention - often caused by improper indentation)
- **MD032**: Lists should be surrounded by blank lines
- **MD047**: Files should end with a single newline character

Document patterns such as:

- "Found 15 MD029 errors across 5 files"
- "MD032 appears in all documentation files"
- "MD029 errors primarily in files with code blocks within lists"

### Phase 4: Automatic Fixes

#### Execute Auto-Fix

Run the auto-fix command to correct all auto-fixable issues:

```bash
markdownlint-cli2 "**/*.md" --fix
```

This command will:

- Automatically fix formatting issues where possible
- Preserve original content intent
- Modify files in place

#### Monitor for Issues

Watch for:

- Errors during the fix process
- Files that couldn't be modified (permissions)
- Any unexpected side effects

Document what was fixed automatically versus what remains.

### Phase 5: Manual Fixes

#### Handle MD029 Issues

For remaining MD029 (ordered list item prefix) issues:

Load and consult `references/MD029-Fix-Guide.md` for detailed guidance on:

- Understanding the root cause: **improper indentation of content between list items**
- Proper 4-space indentation for code blocks within lists
- Indentation requirements for paragraphs, blockquotes, and nested content
- Common mistakes and how to avoid them
- Real-world examples showing before/after fixes
- Alternative solutions and when to use them

**Key insight**: MD029 errors often occur when code blocks, paragraphs, or other content between list items lack proper indentation (typically 4 spaces), causing markdown parsers to break list continuity.

#### Apply Manual Corrections

For issues not auto-fixed:

- Open affected files
- Apply fixes according to error type
- Maintain consistency with existing markdown style
- Verify fixes don't break content

### Phase 6: Verification & Reporting

#### Re-run Linter

Confirm all issues are resolved:

```bash
markdownlint-cli2 "**/*.md"
```

If no errors appear, linting is complete. If errors remain, document them for additional manual fixes.

#### Generate Summary Report

Provide a comprehensive summary including:

1. **Files Processed**
   - Total count
   - List of files modified
   - Any files skipped or with errors

2. **Issues Fixed by Type**
   - Count of each error type fixed
   - Auto-fixed vs. manually fixed
   - Special notes on MD029 fixes

3. **Remaining Issues** (if any)
   - Error codes still present
   - Files requiring manual attention
   - Recommended next steps

4. **Completion Status**
   - Confirmation of successful completion, or
   - Clear explanation of remaining work needed
   - Any error details with suggested solutions

## Quick Reference Checklist

- [ ] Verify markdownlint availability: `markdownlint-cli2 --version`
- [ ] Create or validate markdownlint config (`.markdownlint-cli2.jsonc` preferred)
- [ ] Run diagnostics: `markdownlint-cli2 "**/*.md"`
- [ ] Apply auto-fixes: `markdownlint-cli2 "**/*.md" --fix`
- [ ] Resolve remaining issues manually using `references/MD029-Fix-Guide.md` and `references/MD036-Guide.md` as needed
- [ ] Re-run verification: `markdownlint-cli2 "**/*.md"`
- [ ] Summarize files changed, issue types fixed, and any remaining blockers

## Key Principles

- Preserve content intent: fix formatting without changing meaning.
- Respect project configuration: do not override existing lint rules unless explicitly requested.
- Do not suppress or hide errors without user consent; fix issues rather than masking them.
- Apply progressive fixing: auto-fix first, then manual fixes for remaining issues.
- Report clearly: what was found, what was fixed, and what still needs action.

## Common Scenarios

| User Request Pattern | Workflow Emphasis | References |
| --- | --- | --- |
| "Set up markdown linting for my documentation" | Phase 1 -> Phase 2 -> Phase 4 -> Phase 6 | N/A |
| "Fix all markdown linting errors in my project" | Phase 2 -> Phase 3 -> Phase 4 -> Phase 5 -> Phase 6 | Load MD029/MD036 guides only if related errors remain |
| "Fix MD029" / "ordered list issues" | Phase 2 (target MD029) -> Phase 4 -> Phase 5 -> Phase 6 | `references/MD029-Fix-Guide.md` |

## Resources

### references/

#### MD029-Fix