Markdown Authoring Guidelines

Follow these rules when creating or editing markdown files.

Rules

• Always specify language on code blocks - Use bash, yaml, json, text, hcl, go, etc. Never use bare ```
• No AI slop - Never use emojis, glyphs or emdashes
• Use headings, not bold for section titles - Use proper heading levels (##, ###, etc.) not **Bold** on its own line
• One H1 per file - Only one # Title at the top
• First line should be H1 - Start files with # Title
• Write to the formatter contract - A PostToolUse hook reformats markdown after every write. See /md-lint for what it rewrites and which lint rules it cannot fix
• Blank lines between styles - Put single blank line between different markdown types

Examples

Blank lines between styles