Markdown Formatter

This skill provides modular, categorized formatting guidance for markdown documents. Load resources by formatting area as needed.

Quick Reference: When to Load Which Resource

Core Rules at a Glance

Headers

• ATX-style: Use # notation, not underlines
• One per document: Single H1 at start
• No skips: Go H1 → H2 → H3, never skip levels
• Spacing: Blank line before (except first) and after each header

Lists

• Marker: Use - consistently (not * or +)
• Indentation: 2 spaces per nesting level
• Spacing: Blank line before and after list blocks

Code

• Inline: Single backticks for code references
• Blocks: Fenced (not indented) with language ID
• Spacing: Blank line before and after blocks

Links & Images

• Links: Descriptive text (no "click here")
• References: Use reference-style for repeated URLs
• Images: Always include meaningful alt text

Spacing

• Between blocks: One blank line
• No trailing whitespace: Remove all line-end spaces
• End of file: Single newline

Spacing

• Between blocks: One blank line
• No trailing whitespace: Remove all line-end spaces
• End of file: Single newline

Formatting Workflow

Phase 1: Structural Scan

Check high-level structure first:

1. Read entire file to understand flow
2. Load resources/headers-hierarchy.md if issues found
3. Verify H1 count, levels, and spacing

Phase 2: Block-Level Formatting

Process each formatting category in sequence:

1. Headers → headers-hierarchy.md
2. Lists → lists-nesting.md
3. Code → code-emphasis.md
4. Links/Images → links-images.md

Phase 3: Final Polish

Complete document-level formatting:

1. Load resources/spacing-tables.md
2. Fix spacing around all blocks
3. Validate tables (if present)
4. Check line length and trailing whitespace
5. Verify single trailing newline

Phase 4: Validation

Use validation tools to catch remaining issues:

./skills/markdown-formatter/scripts/validate-markdown.sh file.md

How to Use Resources

Each resource file is self-contained and covers one formatting area:

• Headers: Read full file once for complete header guidance
• Lists: Reference indentation rules and spacing requirements
• Code: Check inline vs. block syntax and language identifiers
• Links/Images: Verify alt text guidelines and reference styles
• Spacing: Apply final polish and table formatting

Resource Structure

Each resource includes:

• Syntax examples (correct and incorrect)
• Rules and guidelines (with explanations)
• Common issues and fixes (before/after)
• Validation checklist (quick verification)

Resource Structure

Each resource includes:

• Syntax examples (correct and incorrect)
• Rules and guidelines (with explanations)
• Common issues and fixes (before/after)
• Validation checklist (quick verification)

Common Formatting Issues

Issue: Inconsistent List Markers

<!-- Before: mixed markers -->
* Item 1
+ Item 2
- Item 3

<!-- After: consistent -->
- Item 1
- Item 2
- Item 3

→ Load resources/lists-nesting.md for full guidance

Issue: Missing Code Block Language

<!-- Before -->

npm install

<!-- After -->
```bash
npm install

→ Load `resources/code-emphasis.md`

### Issue: Skipped Header Levels
```markdown
<!-- Before -->
# Title
### Subsection (skipped H2!)

<!-- After -->
# Title
## Section
### Subsection

→ Load resources/headers-hierarchy.md

Issue: Bad Link Text

<!-- Before -->
Click [here](url) for details

<!-- After -->
See the [installation guide](url)

→ Load resources/links-images.md

Issue: Missing Alt Text

<!-- Before -->
![](screenshot.png)

<!-- After -->
![Dashboard showing user metrics](screenshot.png)

→ Load resources/links-images.md

Output Format

When formatting files, provide:

Summary

• Original line count
• New line count
• Primary issues fixed

Issues Fixed

• List each category of corrections
• Count of fixes per category

Recommendations

• Content improvements (if any)
• Consistency notes
• Accessibility enhancements

Formatting Decision Table

Use this table to decide what to fix and in what order:

| Priori

...