Interpretive guidance for applying markdownlint rules using our opinionated configuration. Use when creating or editing markdown files, configuring markdownlint, troubleshooting linting issues, or reviewing markdown quality.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
default-config.jsoncpitfalls-reference.mdrules-reference.mdtroubleshooting.mdThis skill teaches how to interpret and apply markdownlint rules effectively using our opinionated configuration. It provides guidance on what the rules mean in practice, when exceptions are appropriate, and how our configuration balances strictness with flexibility.
Fetch official markdownlint documentation when needed for reference:
Why fetch: Rules and best practices evolve. This skill interprets the rules; official docs define them.
Key principle: Prioritize readability and practical modern usage over rigid formatting constraints.
What this means:
Decision test: Does this rule enhance readability and consistency, or does it create unnecessary friction?
How markdownlint works:
Important: Not all violations are auto-fixable. Structural issues (heading hierarchy, link format) often require manual intervention.
Official behavior: When "default": true, all rules are enabled unless explicitly overridden.
From official docs: This is the recommended baseline - comprehensive coverage of common markdown issues.
Our philosophy-driven configuration:
See default-config.jsonc in this skill directory for the complete configuration file.
Why these overrides work:
From markdownlint docs:
Syntax:
# Document Title
Introductory paragraph.
## Section Heading
Content here.
### Subsection
More content.
When hierarchy matters:
When to bend rules:
Anti-pattern:
# Title
#### Subsection <!-- ❌ Skipped levels -->
Better:
# Title
## Section
### Subsection <!-- ✅ Proper hierarchy -->
Required behavior (MD046):
Always specify language:
<!-- ❌ No language specified -->
code here
<!-- ✅ Language specified -->
```javascript
code here
**Why:** Enables syntax highlighting, makes intent clear, helps tools process content.
**Language identifiers:**
- `javascript`, `typescript`, `python`, `bash`, `json`, `yaml`, `markdown`
- Use `text` or `plaintext` when no language applies
## Allowed HTML Elements (Best Practices)
**Our configuration allows specific HTML when markdown is insufficient:**
| Element | Use Case | Example |
|---------|----------|---------|
| `<br>` | Line breaks within paragraphs | `Line one<br>Line two` |
| `<details>` + `<summary>` | Collapsible sections | See below |
| `<img>` | Advanced image attributes | `<img src="..." width="100">` |
| `<kbd>` | Keyboard input styling | Press `<kbd>Ctrl</kbd>+<kbd>C</kbd>` |
| `<sub>` / `<sup>` | Subscript/superscript | H<sub>2</sub>O, x<sup>2</sup> |
**Collapsible section pattern:**
```markdown
<details>
<summary>Click to expand</summary>
Content here (can include markdown).
</details>
Anti-pattern:
<!-- ❌ Arbitrary HTML -->
<div class="custom">Content</div>
<!-- ✅ Use allowed elements only -->
<details>
<summary>Custom Section</summary>
Content
</details>
From markdownlint rules:
Link formatting:
<!-- ❌ Bare URL -->
Check https://example.com for details
<!-- ✅ Proper link syntax -->
Check <https://example.com> for details
Check [documentation](https://example.com) for details
Emphasis consistency:
<!-- ✅ Consistent style -->
Use **bold** for strong emphasis
Use *italic* for emphasis
<!-- ❌ Inconsistent -->
Use **bold** and __bold__ mixed
Spacing:
<!-- ❌ Spaces inside markers -->
** bold text **
<!-- ✅ No spaces -->
**bold text**
Problem: Skipping heading levels breaks document outline and navigation.
# Main Title
### Subsection <!-- ❌ MD001: Skipped H2 level -->
Why it fails: Screen readers, table-of-contents generators, and navigation tools expect proper hierarchy.
Better:
# Main Title
## Section
### Subsection <!-- ✅ Proper progression -->
Problem: Using 4-space indentation instead of fenced blocks.
<!-- ❌ Indented code block (MD046) -->
const x = 1;
console.log(x);
Why it fails: No language specification, less explicit, harder to process.
Better:
<!-- ✅ Fenced code block with language -->
```javascript
const x = 1;
console.log(x);
### Pitfall #3: Missing Blank Lines
**Problem:** No spacing around structural elements.
```markdown
# Heading
Content immediately after heading
- List item <!-- ❌ MD032: No blank line before list -->
Why it fails: Reduces readability, can cause parsing ambiguities.
Better:
# Heading
Content with proper spacing.
- List item <!-- ✅ Blank lines around structural elements -->
Problem: Invisible spaces at end of lines.
Why it fails: Causes unnecessary diff noise, some markdown parsers interpret as hard breaks.
Detection: Most editors can highlight trailing whitespace.
Fix: Configure editor to strip trailing whitespace on save, or run markdownlint-cli2 --fix.
The mr-sparkle plugin includes a PostToolUse hook that:
.md, .markdown)markdownlint-cli2 --fix automaticallyWhat this means: Most formatting issues auto-fix on save. Pay attention to reported unfixable issues.
Before finalizing markdown:
From official rules:
Best practices:
**bold**, *italic*)<details> + <summary>/mr-sparkle:lint-md [path]Use when:
Example: /mr-sparkle:lint-md docs/ or /mr-sparkle:lint-md README.md
/mr-sparkle:fix-md [path]Use when:
Note: Not all issues can be auto-fixed. Structural problems require manual intervention.
Example: /mr-sparkle:fix-md docs/ or /mr-sparkle:fix-md .
Detailed guides (loaded on-demand for progressive disclosure):
rules-reference.md - Complete table of markdownlint rules enforcedpitfalls-reference.md - Common mistakes with detailed examplestroubleshooting.md - Debugging guide for common issuesdefault-config.jsonc - Full configuration file with opinionated defaultsOfficial documentation to fetch:
Remember: This skill interprets markdownlint rules and our configuration philosophy. Always fetch official docs for current rule definitions and syntax details.