fabioc-aloha 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
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