# Lint Clean Markdown Skill

> Write markdown that passes linting on first attempt by internalizing common rules. Use when this capability is needed.

- Skill: `tomevault-io/lint-clean-markdown-skill` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/lint-clean-markdown-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lint-clean-markdown-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/lint-clean-markdown-skill

---


# 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 `-`

```markdown
**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:

1. **Inline code** for short examples: ` ```js `
2. **Descriptions** instead of showing wrong examples
3. **Single examples** showing only the correct form

This skill itself demonstrates the solution.

## Pre-Write Mental Checklist

Before writing markdown, plan for:

1. ☐ Will I have lists? → Remember blank lines around them
2. ☐ Will I have code blocks? → Remember blank lines around them
3. ☐ Will I show "wrong" examples? → Can't nest fences, describe instead
4. ☐ Will I have tables? → Need `| ---- |` separator row
5. ☐ Will I have mermaid? → Need diagram type after init

## Synapses

See [synapses.json](synapses.json) for connection mapping.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/fabioc-aloha) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->