---

name: markdown-expert-writer description: Use when creating or editing markdown files to ensure strict compliance with markdownlint rules and professional markdown best practices

Markdown Expert Writer (Strict Markdownlint Compliance)

Overview

This skill enables writing markdown files that strictly comply with all 30+ markdownlint rules. Markdownlint enforces consistency, readability, and compatibility across markdown parsers (kramdown, GitHub, CommonMark). Every markdown file created or edited must pass markdownlint validation with zero violations.

Core principle: Perfect markdown is consistent, readable, and parser-compatible. Every violation of a markdownlint rule represents a choice that reduces one of these qualities.

Markdownlint Rules Reference (All 30+ Rules)

This section documents all rules with violations to avoid. Rules are grouped by category for easy reference.

Headers (MD001-MD026)

Lists (MD004-MD007, MD029-MD030)

Code Blocks (MD031, MD040, MD046)

Emphasis & Links (MD011, MD036-MD039)

Whitespace (MD009-MD010, MD012, MD027-MD028)

Blockquotes & Horizontal Rules (MD035)

Inline HTML (MD033)

Code Commands (MD014)

Blank Lines Around Blocks (MD032)

File Structure (MD041, MD047)

Perfect Markdown Pattern

Here is a complete markdown file that violates ZERO markdownlint rules:

Copy# Document Title

## Overview

This is the main overview section. Markdown must follow strict rules for consistency and parser compatibility.

### Subsection

This is a subsection with explanation.

## Key Concepts

Here are the key points:

* First item
* Second item
* Third item

## Code Example

Here's a code example:

```python
def hello_world():
    print("Hello, world!")

Lists

Both ordered and unordered lists are supported:

1. First step
2. Second step
3. Third step

Nested Lists

Proper nesting with 3 spaces:

• Item 1
  • Nested 1.1
  • Nested 1.2
• Item 2
  • Nested 2.1

Links and References

Here are proper links:

• Link text
• https://example.com

Code Inline

Use backticks for inline code: const x = 5;

Blockquotes

Proper blockquotes with blank lines:

This is a blockquote.

This is the same blockquote continued.

Here's text after the blockquote.

Emphasis

Proper emphasis without spaces:

• Bold text should not have spaces inside
• Italic text should not have spaces inside

Horizontal Rule

Use consistent horizontal rules:

---

Conclusion

This document follows all markdownlint rules.

Copy
**Key observations about perfect markdown:**
1. **First line is h1 header** (`# Document Title`)
2. **Headers increment by 1** (h1 → h2 → h3, never h1 → h3)
3. **Headers surrounded by blank lines** (blank before and after)
4. **No trailing punctuation** on headers
5. **Single space after hash** (`# Title` not `#Title` or `#  Title`)
6. **Consistent list markers** (all `*` or all `-`, never mixed)
7. **3-space indentation** for nested lists (or configured default)
8. **Blank lines around lists** (before first item, after last item)
9. **Fenced code blocks with language** (`` ```python `` not `` ``` ``)
10. **Blank lines around code blocks**
11. **No trailing spaces** at end of lines
12. **No hard tabs** (use spaces)
13. **Links in brackets/parentheses** (`[text](url)`)
14. **No multiple blank lines** (max 1 between sections)
15. **Single newline at end of file**

## Practical Rules for Compliance

### Rule #1: Start Every File Correctly

```markdown
# File Title

This is the first content after the title.

Every file MUST:

• ✅ Start with # Title (h1 header)
• ✅ Have blank line after title
• ✅ Have exactly one space after #
• ✅ Have no trailing punctuation

Rule #2: Use Consistent Header Hierarchy

Copy# Main Title (H1)

## Section One (H2)

### Subsection 1.1 (H3)

Some content.

### Subsection 1.2 (H3)

More content.

## Section Two (H2)

Content here.

Must follow this pattern:

• ✅ Increment by exactly 1 level (h1 → h2 → h3, never h1 → h3)
• ✅ Never skip levels
• ✅ Only one h1 in document (the title)
• ✅ Each header surrounded by blank lines
• ✅ Headers start at column 0 (no indentation)

Rule #3: Format Lists Correctly

Unordered lists (pick one marker, use consistently):

Copy* Item 1
* Item 2
* Item 3

Nested unordered (3 space indent):

Copy* Item 1
   * Nested item 1.1
   * Nested item 1.2
* Item 2
   * Nested item 2.1

Ordered lists (always use 1.):

Copy1. First step
1. Second step
1. Third step

Nested ordered (3 space indent):

Copy1. Step 1
   1. Substep 1.1
   1. Substep 1.2
1. Step 2
   1. Substep 2.1

List requirements:

• ✅ Blank line BEFORE first item
• ✅ Blank line AFTER last item
• ✅ Consistent marker throughout (all * or all -, never mixed)
• ✅ Exactly 1 space after marker
• ✅ Nested items use 3 spaces (not 2, not 4)
• ✅ No hanging indents unless using multi-paragraph items

Rule #4: Format Code Blocks

Fenced code blocks (preferred):

CopyHere's an example:

```python
def hello():
    return "world"

More text after.

Copy
**Requirements:**
- ✅ Blank line before opening fence
- ✅ Blank line after closing fence
- ✅ Always specify language (`` ```python `` not `` ``` ``)
- ✅ Use consistent fence character (always `` ``` ``)
- ✅ Use fenced, not indented code blocks

**Inline code (backticks):**

```markdown
Use the `const` keyword or `let` for variables.

Requirements:

• ✅ No spaces inside backticks: `code` not ` code `
• ✅ Use for short code snippets only

Rule #5: Format Links and URLs

Proper link syntax:

Copy[Link text](https://example.com)

Bare URLs must have angle brackets:

Copy<https://example.com>

NOT valid:

Copy❌ (Link text)[https://example.com]  (reversed syntax)
❌ https://example.com  (bare URL)
❌ [ Link ](url)  (spaces inside brackets)

Rule #6: Format Emphasis

Bold (no spaces inside):

CopyThis is **bold text**.

Italic (no spaces inside):

CopyThis is *italic text*.

NOT valid:

Copy❌ This is ** bold ** text  (spaces inside)
❌ This is * italic * text  (spaces inside)

Rule #7: Use Headers, Not Bold, for Sections

Correct:

Copy## Important Section

Content goes here.

NOT valid:

Copy❌ **Important Section**

Content goes here.

Rule #8: Use Blockquotes Properly

Correct syntax with continuation:

Copy> This is a blockquote.
>
> This is the same blockquote continued.

Here's text after the blockquote.

NOT valid:

Copy❌ > Quote 1
❌ 
❌ > Quote 2
(This creates two separate quote blocks with potential parser issues)

Rule #9: Use Consistent Horizontal Rules

CopySome content above.

---

Some content below.

Requirements:

• ✅ Use same symbol throughout (e.g., all ---)
• ✅ Have blank line before and after
• ✅ Use 3+ consecutive characters

NOT valid:

Copy❌ ---    (some uses)
❌ ***    (other uses - inconsistent)

Rule #10: File Structure

Valid file start and end:

Copy# Title

Content...

More content...
[EOF with newline]

Requirements:

• ✅ Start with # Title (h1 header)
• ✅ End with newline character (no text right before [EOF])
• ✅ No characters after final newline
• ✅ All lines <80 characters (except URLs or code)

NOT valid:

Copy❌ This file starts with text, not header
❌ Text[EOF]  (no final newline)
❌ [EOF][EOF]  (multiple final newlines)

Line Length Guidelines

Wrapping strategy:

CopyThis is a very long line that exceeds the 80 character limit and needs to be
wrapped to meet markdown best practices for readability and consistency with
lint rules.

Common Mistakes & Fixes

Validation Checklist Before Submitting

Before considering any markdown file complete, verify:

• MD001: No skipped header levels (h1 → h2 → h3, never h1 → h3)
• MD002: First header is h1 (# Title)
• MD003: Header style consistent (all ATX atx style with #)
• MD004: Unordered list markers consistent (all * or all -)
• MD005: List items at same level have same indentation
• MD006: Top-level lists start at column 0 (not indented)
• MD007: Nested list indentation consistent (3 or 4 spaces)
• MD009: No trailing spaces at end of lines
• MD010: No hard tabs (use spaces for indentation)
• MD011: Links have correct syntax [text](url) not (text)[url]
• MD012: No multiple consecutive blank lines
• MD013: Lines <80 characters (except URLs)
• MD014: No $ in code blocks unless showing output
• MD018: Space after # in headers (# Header not #Header)
• MD019: Only one space after # in headers (# Header not # Header)
• MD020: Closed headers have spaces: # Header #
• MD021: Only one space in closed headers: # Header # not # Header #
• MD022: Headers surrounded by blank lines (except file edges)
• MD023: Headers start at column 0 (no indentation)
• MD024: Each header has unique text
• MD025: Only one h1 header (top level)
• MD026: Headers end without punctuation (. , ; : ! ?)
• MD027: One space after blockquote marker: > Quote not > Quote
• MD028: Blockquotes properly separated or continued with >
• MD029: Ordered lists use 1. prefix consistently
• MD030: Exactly 1 space after list markers
• MD031: Code blocks surrounded by blank lines
• MD032: Lists surrounded by blank lines
• MD033: No inline HTML (use markdown)
• MD034: URLs wrapped in angle brackets: <url>
• MD035: Horizontal rules consistent (--- or ***)
• MD036: Sections use headers, not bold text
• MD037: No spaces inside emphasis: **bold** not ** bold **
• MD038: No spaces inside code: `code` not ` code `
• MD039: No spaces inside link text: [text](url) not [ text ](url)
• MD040: Code blocks have language specified
• MD041: First line is h1 header
• MD046: Code blocks use fenced syntax, not indentation
• MD047: File ends with single newline

Real-World Examples

Example 1: Project README

Copy# MyProject

## Overview

MyProject is a framework for...

## Installation

To install MyProject:

```bash
npm install myproject

Usage

Here's a basic example:

Copyconst mp = require('myproject');

mp.start();

Features

• Fast and lightweight
• Easy to use
• Well documented
  • API docs
  • Examples
  • Tutorials

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT

Copy
**Validates:**
- ✅ Starts with `# MyProject` (h1)
- ✅ Headers increment by 1 level
- ✅ All headers surrounded by blank lines
- ✅ Code blocks have language
- ✅ Lists use consistent markers
- ✅ Proper list nesting
- ✅ Ends with newline

## References

**Markdownlint Official Documentation:**
- Rules: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
- Style guide: https://cirosantilli.com/markdown-style-guide
- GitHub markdown: https://guides.github.com/features/mastering-markdown/

**Validation Tools:**
- Online: https://www.markdownlint.com/ (paste markdown to validate)
- CLI: `npm install -g markdownlint-cli`
- Pre-commit hook: Configure `.markdownlintrc` in repository root