Add markdown linting infrastructure

[plx]

Summary

• Add markdownlint-cli2 for linting content markdown files
• Add .markdownlint.yaml config tuned for this project (frontmatter, prose content, MDX compatibility)
• Add npm run lint:markdown script and just lint-markdown command

Notes

Not yet integrated into CI or validate:all — existing content has 19 lint errors (skipped heading levels, excessive blank lines, list formatting) that should be fixed first. The follow-up heading hierarchy PR will fix the content and integrate linting into CI.

Test plan

• Run just lint-markdown and verify it reports known issues
• Verify just build still passes
• Verify CI passes (no changes to workflow)

🤖 Generated with Claude Code

[github-actions]

PR Validation ✅

All checks passed! Ready for review.

Checks Performed:

✓ Linting
✓ Spell check (source)
✓ Type checking & Build
✓ Spell check (HTML)
✓ Internal link validation
✓ Artifact upload

This is a complete dry-run of the deployment process, ensuring your changes will deploy successfully when merged.

[claude]

markdownlint configuration

See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

Heading hierarchy rules

MD001: true # heading-increment - headings should only increment by one level at a time
MD025: true # single-title/single-h1 - documents should have a single top-level heading

Heading style rules

MD003: # heading-style - heading style should be consistent
style: atx # Use ATX style (##) not Setext style (underlines)
MD018: true # no-missing-space-atx - no space after hash on atx style heading
MD019: true # no-multiple-space-atx - multiple spaces after hash on atx style heading
MD023: true # heading-start-left - headings must start at the beginning of the line
MD024: # no-duplicate-heading - multiple headings with the same content
siblings_only: true # Allow duplicate headings in different sections
MD026: # no-trailing-punctuation - trailing punctuation in heading
punctuation: ".,;:!" # Don't allow these, but allow ? for questions

First line rules

MD041: false # first-line-heading/first-line-h1 - disabled because we use frontmatter

Line length

MD013: false # line-length - disabled for prose content

Code blocks

MD046: # code-block-style - code block style should be consistent
style: fenced # Use fenced code blocks (```) not indented

Lists

MD004: # ul-style - unordered list style should be consistent
style: dash # Use dashes for unordered lists
MD029: # ol-prefix - ordered list item prefix
style: ordered # Use sequential numbers (1, 2, 3) not all 1s
MD030: # list-marker-space - spaces after list markers
ul_single: 1
ul_multi: 1
ol_single: 1
ol_multi: 1

Blank lines

MD012: # no-multiple-blanks - multiple consecutive blank lines
maximum: 2 # Allow up to 2 blank lines for visual separation
MD022: # blanks-around-headings - headings should be surrounded by blank lines
lines_above: 1
lines_below: 1

Inline HTML

MD033: false # no-inline-html - disabled to allow inline HTML in MDX

Emphasis

MD036: false # no-emphasis-as-heading - disabled to allow emphasized text that looks like headings

Whitespace and formatting

MD009: false # no-trailing-spaces - disabled as trailing spaces don't affect rendering
MD007: false # ul-indent - disabled to allow flexible list indentation
MD060: false # table-column-style - disabled as table alignment is cosmetic