md-lint

STARTER_CHARACTER = 🔏

Markdown Formatter Contract

A PostToolUse hook runs markdownlint-cli2 --fix and then prettier --write on every markdown file written or edited, excluding .llmtmp/, .llmdocs/, SKILL.md, and plan files. Writing to this contract avoids a rewrite, and a rewrite invalidates the in-context copy of the file.

What prettier rewrites

Input	Output
* item, + item	- item
1) ordered marker	1.
*emphasis*	_emphasis_
__strong__	**strong**
*** thematic break	---
Two or more blank lines	One blank line
Runs of spaces inside a line	Single space
Unpadded table cells	Cells padded to column width
No trailing newline	Trailing newline added

Prose is not rewrapped. Long lines stay as written.

What markdownlint fixes

Missing space after #, missing blank lines around headings and fenced blocks, trailing whitespace, and bare URLs.

Four rules are off: MD013 (line length), MD024 (duplicate headings), MD029 (ordered list prefix), MD033 (inline HTML).

What neither can fix

These reach the model as hook feedback and need a manual edit:

• MD003, heading style. Setext headings underlined with === or --- are errors. Use ATX (#, ##).
• MD025, one H1 per document.
• MD045, images need alt text.
• MD042, links need a destination.
• MD040, fenced code blocks need a language.

Writing conforming markdown

Start with a single # Title. Use ATX headings, - bullets, _emphasis_, **strong**, one blank line between blocks, a language on every fence, alt text on every image, and a trailing newline.