markdown-validation

# Markdown Validation

Validate markdown files after writing or editing them.

## Iron Law

**Always run markdownlint after writing markdown. Fix ALL errors before
proceeding.**

This is not optional. This is not negotiable. Markdown files that fail linting
create inconsistency and maintenance burden.

## Workflow

```text
Write/Edit markdown file
        │
        ▼
Run markdownlint on file
        │
        ▼
    ┌───────────┐
    │  Errors?  │
    └───────────┘
        │
   ┌────┴────┐
   │         │
   ▼         ▼
  Yes        No
   │         │
   ▼         ▼
Fix errors  Done
   │
   ▼
Re-run markdownlint
   │
   ▼
(repeat until no errors)
```

## Process

### 1. Run Validation

After writing or editing a markdown file, run:

```bash
markdownlint <file-path>
```

### 2. Interpret Results

**No output**: File passes validation. Proceed.

**Error output**: Fix each error before proceeding.

Common errors:

| Code  | Issue                       | Fix                              |
| ----- | --------------------------- | -------------------------------- |
| MD001 | Heading level increment     | Use sequential heading levels    |
| MD009 | Trailing spaces             | Remove trailing whitespace       |
| MD012 | Multiple blank lines        | Use single blank lines           |
| MD022 | Headings need blank lines   | Add blank line before/after      |
| MD031 | Fenced code needs blanks    | Add blank line before/after      |
| MD032 | Lists need blank lines      | Add blank line before/after list |
| MD034 | Bare URL                    | Use proper link syntax           |
| MD047 | No newline at end of file   | Add final newline                |

### 3. Fix Errors

For each error:

1. Read the error message and line number
2. Navigate to the specific location
3. Apply the fix
4. Re-run validation

**Do not proceed until all errors are fixed.**

### 4. Confirm Success

Only after markdownlint returns no errors:

```text
Markdown validation passed for <file-path>.
```