I’ve been spending an awful lot of time with Claude Code as of late (including passing the Claude Code in Action course, because I do love badges).
The lingua franca of coding agents seems to be Markdown, which is totally cool, I’m a big fan. But in my experience to date (which involves a bunch of Spec Kit), Claude models don’t write syntactically correct Markdown every time. Admittedly I haven’t tried other models, and Opus 4.6 just came out yesterday so maybe things will improve, but for now there seem to be a couple consistent problems:
- Emphasis is used in place of properly hierarchical headers (violates MD036)
- Lists are not proceeded by a line break (which will cause the list items to run together when rendered)
- Items that should be on multiple lines do not have an extra line break between them (again, causing them to render as a single line)
I got tired of these issues, and thus created a simple set of instructions to tell Claude not to do the above, and a hook to automatically lint all markdown files and tell the model to fix any issues that slip through. Dropped these into my global configuration, and so far, so good!
Here’s my CLAUDE.md:
## Markdown Formatting
When generating or editing markdown files, always follow these rules for proper rendering:
- Use `-` for unordered lists, `1.` for ordered lists (not `*` or other markers)
- Include a blank line before bulleted (`-`) or numbered (`1.`) lists
- Include a blank line before fenced code blocks (```)
- Include a blank line before headers (`#`, `##`, etc.) except at file start
- Include a blank line between headers and content
- Do not use emphasis (`**`) as a header
- Always specify a language in a fenced code block
- Include a blank line between lines that should be rendered on separate lines
And my settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "npx markdownlint-cli --disable MD013 -- \"**/*.md\" || $(exit 2)"
}
]
}
]
}
}
That little bit at the end of the command is important, because a post tool use hook must return an exit code of 2 to let Claude know that something needs tending (and markdownlint-cli doesn’t return that code by default when there’s a problem).
Hope these are helpful!
