Markdown Expert Writer

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:

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

```csharp
public static void HelloWorld()
{
    Console.WriteLine("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.

**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

# 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):

* Item 1
* Item 2
* Item 3

Nested unordered (3 space indent):

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

Ordered lists (always use 1.):

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

Nested ordered (3 space indent):

1. 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):

Here's an example:

```csharp
public static string Hello()
{
    return "world";
}

More text after.

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

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

Bare URLs must have angle brackets:

<https://example.com>

NOT valid:

❌ (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):

This is **bold text**.

Italic (no spaces inside):

This is *italic text*.

NOT valid:

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

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

Correct:

## Important Section

Content goes here.

NOT valid:

❌ **Important Section**

Content goes here.

Rule #8: Use Blockquotes Properly

Correct syntax with continuation:

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

Here's text after the blockquote.

NOT valid:

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

Rule #9: Use Consistent Horizontal Rules

Some 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:

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

Rule #10: File Structure

Valid file start and end:

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

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

Line Length Guidelines

Wrapping strategy:

This 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

# MyProject

## Overview

MyProject is a framework for...

## Installation

To install MyProject:

```powershell
dotnet add package MyProject

Usage

Here's a basic example:

var mp = new 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

**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