Markdown Clean Skill

Write clean, error-free markdown that IDEs and linters can parse without warnings.

When to Use

Invoke this skill when:

• Writing markdown documentation
• Creating README files
• Writing skill files with code examples
• Commands: /md-clean, /markdown

Common IDE Errors & Fixes

1. Nested Code Blocks

Problem: Code blocks inside code blocks cause parsing errors.

Error: Newline or semicolon expected

Wrong: ````markdown

Here is example:

const x = 1;

````

Fix: Use different fence lengths (4 backticks for outer):

````markdown ```markdown Here is example:

const x = 1;

``` ````

Or use indentation for inner blocks:

````markdown

Here is example:

    const x = 1;

````

2. Unclosed Code Blocks

Problem: Missing closing fence.

Error: Statement expected, Expression expected

Wrong:

const x = 1; // forgot to close

**Fix:** Always close with matching fence:

const x = 1;
```                    <-- closing fence

3. Mismatched Fence Characters

Problem: Opening with backticks, closing with tildes (or vice versa).

Error: Newline or semicolon expected

Wrong:

const x = 1;

Fix: Match opening and closing:

const x = 1;

4. Special Characters in Code Blocks

Problem: Unescaped backticks inside code blocks.

Error: Unexpected token

Wrong: ````markdown

Use `code` for inline.

````

Fix: Use more backticks for outer fence:

````markdown ``markdown Use code for inline. `` ````

5. Pipe Characters in Tables

Problem: Unescaped | in table cells.

Error: Column count mismatch

Wrong:

| Command | Description |
|---------|-------------|
| a | b | Creates a|b |

Fix: Escape with backslash:

| Command | Description |
|---------|-------------|
| a \| b | Creates a\|b |

6. HTML in Markdown

Problem: Unclosed HTML tags.

Error: Tag not closed

Wrong:

<details>
<summary>Click</summary>
Content here

Fix: Close all tags:

<details>
<summary>Click</summary>
Content here
</details>

7. Link Syntax Errors

Problem: Malformed links.

Error: ) expected, ] expected

Wrong:

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

Fix: Proper syntax:

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

[ref]: https://example.com

8. List Indentation

Problem: Inconsistent indentation in nested lists.

Error: Unexpected indent

Wrong:

- Item 1
   - Nested (3 spaces - inconsistent)
  - Another (2 spaces)

Fix: Consistent indentation (2 or 4 spaces):

- Item 1
  - Nested (2 spaces)
  - Another (2 spaces)

9. Heading Syntax

Problem: No space after #.

Error: May not render as heading

Wrong:

#Heading
##Another

Fix: Space after #:

# Heading
## Another

10. Empty Lines Around Blocks

Problem: Missing blank lines before/after code blocks.

Error: Unexpected token

Wrong:

Some text

code

More text

Fix: Add blank lines:

Some text

code

More text

Fence Level Guide

Use increasing backticks for nesting:

Safe Markdown Template

# Title

Brief description.

## Section 1

Regular paragraph text.

### Subsection

- List item 1
- List item 2
  - Nested item

## Code Example

code here

## Table

| Col 1 | Col 2 |
|-------|-------|
| A | B |

## Links

- [Text](https://url.com)
- [Reference][ref]

[ref]: https://url.com

Validation Checklist

Before saving markdown:

• All code blocks have closing fences
• Fence characters match (`` with ``)
• Nested blocks use longer fences
• Tables have equal column counts
• All pipes in tables are escaped
• HTML tags are closed
• Links have proper syntax
• Lists use consistent indentation
• Headings have space after #
• Blank lines around code blocks

Quick Fixes

Escaping Reference

Characters to escape in specific contexts:

IDE-Specific Tips

VS Code

• Install "markdownlint" extension
• Enable "Format on Save"
• Use preview pane to verify

JetBrains (WebStorm, IntelliJ)

• Enable Markdown plugin
• Check "Problems" panel
• Use "Reformat Code" (Cmd/Ctrl+Alt+L)

Vim/Neovim

• Use vim-markdown plugin
• Enable conceallevel for preview
• Run :MarkdownPreview

Validation Script

Use the included validation script to check markdown files:

# Validate single file
python scripts/validate.py README.md

# Validate directory
python scripts/validate.py ./docs

# Sample output
README.md:15:1: error [MD001] Unclosed code block
    Suggestion: Add closing ``` fence
README.md:42:1: warning [MD003] No space after heading hashes
    Suggestion: Add space: ## Heading...

Error Codes