markdown-linting

What this skill does

# Markdown Linting

This skill provides comprehensive guidance for markdown linting using `markdownlint-cli2`, the industry-standard markdown linter that can be used in any project.

## Table of Contents

- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Markdown Flavors](#markdown-flavors)
- [First Use: Installation and Setup](#first-use-installation-and-setup)
- [Setting Up Markdown Linting in Your Repo](#setting-up-markdown-linting-in-your-repo)
- [Quick Start](#quick-start)
- [Unified Tooling Architecture](#unified-tooling-architecture)
- [CRITICAL: Configuration Policy](#critical-configuration-policy)
- [CRITICAL: NO AUTOMATED SCRIPTS](#critical-no-automated-scripts)
- [Running Linting Locally](#running-linting-locally)
- [Intelligent Fix Handling](#intelligent-fix-handling)
- [VS Code Extension Setup (Optional/Advanced)](#vs-code-extension-setup-optionaladvanced)
- [GitHub Actions Integration (Optional/Advanced)](#github-actions-integration-optionaladvanced)
- [Customizing Rules (Requires Approval)](#customizing-rules-requires-approval)
- [Troubleshooting](#troubleshooting)
- [Best Practices](#best-practices)
- [Resources](#resources)
- [Evaluation Scenarios](#evaluation-scenarios)
- [Multi-Model Testing Notes](#multi-model-testing-notes)
- [Version History](#version-history)
- [Last Updated](#last-updated)

## Overview

This tooling enables enforcement of strict markdown quality standards through automated linting. Markdown files can be validated using `markdownlint-cli2` with a unified tooling approach that ensures zero configuration drift across VS Code, CLI, and CI/CD environments.

**Core Philosophy:**

- Single source of truth: `.markdownlint-cli2.jsonc` contains all configuration (rules, ignores, options)
- Unified tooling: Same `markdownlint-cli2` engine everywhere (VS Code, CLI, CI/CD)
- Strict enforcement: Fix content to comply with rules, not rules to accommodate content
- Quality-first: Linting rules are intentional and enforce documentation quality

## When to Use This Skill

This skill should be used when:

- User encounters markdown linting errors (MD001, MD013, MD033, etc.)
- User asks about markdown validation, formatting, or quality standards
- User needs to configure `.markdownlint-cli2.jsonc` (rules, ignores, or options)
- User asks about configuration file setup or structure
- User wants to set up VS Code markdown linting extension
- User needs to troubleshoot markdown linting issues
- User asks how to run markdown linting locally
- User wants to understand GitHub Actions markdown validation
- User is working with markdown files and needs quality guidance

## Markdown Flavors

markdownlint-cli2 supports multiple markdown flavors. By default, it validates GitHub Flavored Markdown (GFM), which is recommended for most projects.

**Supported Flavors:**

| Flavor | Default | Best For |
|--------|:-------:|----------|
| **GFM** | ✓ | GitHub repos, most web projects |
| **CommonMark** | | Maximum portability, strict compliance |

**Quick Guidance:**

- **Use GFM (default)** for GitHub repos, typical web projects, and when you need tables/task lists
- **Use CommonMark** for cross-platform publishing or strict standards compliance

**For detailed flavor guidance**, see the dedicated reference files:

- [Flavors Overview](references/flavors/overview.md) - Comparison and selection guidance
- [GFM Configuration](references/flavors/gfm.md) - GitHub Flavored Markdown (default)
- [CommonMark Configuration](references/flavors/commonmark.md) - Strict base specification

**Flavor-Sensitive Rules:**

Some rules only apply to specific flavors. See [Markdownlint Rules Reference](references/markdownlint-rules.md) for rules tagged with their flavor compatibility.

## First Use: Installation and Setup

**If this is your first time setting up markdown linting**, see the comprehensive installation guide:

**[Installation and Setup Guide](references/installation-setup.md)**

This guide covers:

- Prerequisites (Node.js/npm)
- Detection of existing setup
- Two approaches: npx (zero setup) vs local install (full features)
- Configuration file creation (`.markdownlint-cli2.jsonc`)
- Configuring rules, ignores, and options in one file
- Verification steps
- Troubleshooting setup issues

**Quick detection check:**

```bash
# Check if you're already set up
ls .markdownlint-cli2.jsonc     # Configuration exists?
npm list markdownlint-cli2      # Package installed?
cat package.json | grep "lint:md"  # Scripts configured?
```

If any of these are missing, follow the [Installation and Setup Guide](references/installation-setup.md) first.

## Setting Up Markdown Linting in Your Repo

This section provides a complete guide for setting up markdown linting from scratch in any repository.

### Prerequisites

**Node.js 20+** is required. Install via [fnm](https://github.com/Schniz/fnm) (recommended):

```bash
# Windows (PowerShell as Admin)
winget install Schniz.fnm

# macOS/Linux
curl -fsSL https://fnm.vercel.app/install | bash
```

Then in Git Bash, add to `~/.bashrc`:

```bash
eval "$(fnm env --use-on-cd --shell bash)"
```

Install Node:

```bash
fnm install 24 && fnm default 24
```

**Why fnm?** Unlike nvm-windows, fnm works natively in Git Bash without [silent output bugs](https://github.com/coreybutler/nvm-windows/wiki/Common-Issues).

### Step 1: Create Configuration

Create `.markdownlint-cli2.jsonc` in your repo root:

```jsonc
{
  "gitignore": true,
  "config": {
    "default": true,
    "MD013": false
  }
}
```

See [Markdownlint Rules Reference](references/markdownlint-rules.md) for all rules.

### Step 2: Add to package.json

If you don't have a `package.json`, create one:

```json
{
  "name": "your-repo-name",
  "private": true,
  "scripts": {
    "lint:md": "markdownlint-cli2 \"**/*.md\"",
    "lint:md:fix": "markdownlint-cli2 \"**/*.md\" --fix"
  },
  "devDependencies": {
    "markdownlint-cli2": "^0.20.0"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}
```

Then install:

```bash
npm install
```

### Step 3: Add to .gitignore

Ensure `node_modules/` is in your `.gitignore`:

```gitignore
node_modules/
```

### Step 4: Add CI Workflow (Optional)

Create `.github/workflows/markdown-lint.yml`:

```yaml
name: Markdown Lint

on:
  pull_request:
    paths: ['**.md']
  push:
    branches: [main]
    paths: ['**.md']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: DavidAnson/markdownlint-cli2-action@v22
        with:
          globs: '**/*.md'
```

### Step 5: Run Linting

```bash
npm run lint:md        # Check
npm run lint:md:fix    # Auto-fix
```

### Verification Checklist

- [ ] `.markdownlint-cli2.jsonc` exists with your rules
- [ ] `package.json` has lint:md scripts
- [ ] `node_modules/` is in `.gitignore`
- [ ] `npm run lint:md` works locally
- [ ] CI workflow runs on PRs (if added)

## Quick Start

**Option 1: Using npx (zero setup required):**

```bash
# Check all markdown files
npx markdownlint-cli2 "**/*.md"

# Auto-fix issues
npx markdownlint-cli2 "**/*.md" --fix
```

**Option 2: Using npm scripts (if configured):**

```bash
# Check all markdown files for linting errors
npm run lint:md

# Auto-fix fixable linting issues
npm run lint:md:fix
```

**Option 3: VS Code extension for real-time linting (optional/advanced):**

1. Install `davidanson.vscode-markdownlint` from VS Code marketplace
2. Create `.markdownlint-cli2.jsonc` configuration (see installation guide)
3. Linting happens as you type with auto-fix on save enabled (if configured)

## Unified Tooling Architecture

When configured, `markdownlint-cli2` can be used everywhere to ensure zero configuration drift:

### Tooling Components

1. **CLI Tool** (`markdownlint-cli2`) - **Core component, use this first**
   - Can be run via npx (zero setup) or local install
   - Used for local validation and pre-commit checks
   - Foundation for all other integrations

2. **VS Code Extension** (`davidanson.vscode-markdo