Lint-Clean Markdown Skill
Write markdown that passes linting on first attempt by internalizing common rules.
Purpose
Eliminate the edit-lint-fix cycle by writing markdown correctly the first time. This skill encodes the most common markdown lint rules as muscle memory.
The Golden Rule
When in doubt: Add a blank line.
90% of markdown lint errors are missing blank lines. Lists, code blocks, and headings all need breathing room.
Core Rules Quick Reference
| Rule | Code | Pattern | Mnemonic |
|---|---|---|---|
| Blank lines around lists | MD032 | \n- item\n- item\n | "Lists breathe" |
| Blank lines around fences | MD031 | \n```code```\n | "Code breathes" |
| Blank line before headings | MD022 | text\n\n## Head | "Headers breathe" |
| Use dash for lists | MD004 | - not * or + | "Dash dash dash" |
| No trailing whitespace | MD009 | No spaces at line end | "Clean endings" |
| Single final newline | MD047 | One \n at EOF | "One newline" |
| Language on fences | MD040 | ```js not ``` | "Name your code" |
| Consistent fence style | MD046 | Use ``` not indent | "Fences only" |
| No bold as heading | MD036 | Use ## not **text** | "Headers are headers" |
| Table separator spacing | MD060 | Space around pipes | "Tables breathe too" |
Rule Details
MD032: Blank Lines Around Lists
❌ Wrong: Text immediately before/after list
✅ Correct: Blank line before first - AND after last -
**Why**: - Reason one - Reason two **Result**: Something
MD031: Blank Lines Around Code Blocks
❌ Wrong: Text touching the fence markers
✅ Correct: Blank line before opening ``` AND after closing ```
MD022: Blank Lines Before Headings
❌ Wrong: Some text.\n## Heading
✅ Correct: Some text.\n\n## Heading
MD004: Use Dash for Unordered Lists
❌ Wrong: * item or + item
✅ Correct: - item
MD040: Specify Language on Fenced Code
❌ Wrong: ``` (no language)
✅ Correct: ```javascript or ```text or ```markdown
Mermaid-Specific Rules
Template Blocks Use text
When showing a template/pattern (not a renderable diagram), use ```text instead of ```mermaid.
Why: Mermaid parser will fail on placeholder text like [DIAGRAM_TYPE].
Diagram Type Required
After %%{init}%%, must immediately have diagram type: flowchart, sequenceDiagram, graph, etc.
❌ Wrong: %%{init}%% then content directly
✅ Correct: %%{init}%%\nflowchart LR then content
Nested Code Block Problem
You cannot nest fenced code blocks in markdown.
When documenting code block rules (like this skill), use:
- •Inline code for short examples:
```js - •Descriptions instead of showing wrong examples
- •Single examples showing only the correct form
This skill itself demonstrates the solution.
Pre-Write Mental Checklist
Before writing markdown, plan for:
- •☐ Will I have lists? → Remember blank lines around them
- •☐ Will I have code blocks? → Remember blank lines around them
- •☐ Will I show "wrong" examples? → Can't nest fences, describe instead
- •☐ Will I have tables? → Need
| ---- |separator row - •☐ Will I have mermaid? → Need diagram type after init
Synapses
See synapses.json for connection mapping.