---
name: markdown-linting
description: Markdown formatting standards following markdownlint practices
applyTo: [markdown]
---

# Markdown Linting Skill

This skill documents markdown formatting standards for this project, following markdownlint practices.

## Core Rules

### Headings
- Use `#` for headings (not underlines with `===` or `---`)
- Headings must have space after `#`: `# Heading` ✓, `#Heading` ✗
- Heading levels must increment by 1: `# > ## > ###` (don't skip levels)
- File must start with a level 1 heading (H1)
- Use sentence case for headings (capitalize only first word unless proper noun)

### Line Endings & Spacing
- Trim trailing whitespace at end of lines
- No more than one blank line between elements
- Use consistent list marker spacing: 1 space after marker
- Between major sections: exactly 1 blank line

### Lists
- Use `-` for unordered lists (not `*` or `+`)
- Lists must be indented consistently (2 spaces or 4 spaces)
- Ordered lists use `1. 2. 3.` (always `1.` for first item)
- List items with multiple paragraphs: indent continuation 4 spaces
- Blank line before and after lists (if between other content)

### Code
- Inline code with backticks: `` `code` ``
- Code blocks use triple backticks with language: ` ```php `, ` ```bash `, ` ```json `
- Blank line before code block
- Blank line after code block
- Use fenced code blocks (` ``` `), not indentation

### Links & Images
- Use reference-style or inline links: `[text](url)`
- Image syntax: `![alt text](path/to/image.png)`
- URLs must be valid and properly formatted
- Don't use bare URLs (wrap in `<>` or use markdown link syntax)

### Emphasis
- Use `**bold**` for bold (not `__bold__`)
- Use `*italic*` for italic (not `_italic_`)
- Underscores on word boundaries only

### Line Length
- Keep lines under 120 characters where practical
- Long URLs and code blocks are exceptions
- Wrap long text at sentence boundaries

### Blockquotes
- Use `>` for blockquotes with space after: `> quote` ✓
- Blank line after blockquote if followed by text

## Template Structure

### Documentation Files

```markdown
# Main Title

Brief introduction (1-2 sentences).

## Section One

Content here.

### Subsection

Details.

## Section Two

More content.

## See Also

- [Link text](url)
```

### API Documentation

```markdown
# API Endpoint Name

Brief description.

## Overview

What this does.

## Prerequisites

- Prerequisite 1
- Prerequisite 2

## Usage

### Request

```bash
curl command
```

### Response

```json
json example
```

## Configuration

- Option 1: description
- Option 2: description

## Troubleshooting

### Problem

Solution.

## See Also

- [Related](link)
```

### Guides & Tutorials

```markdown
# Tutorial Title

Brief intro.

## Prerequisites

- Item 1

## Step 1: Title

Description and code.

## Step 2: Title

Description and code.

## Verification

How to test.

## Troubleshooting

Issues and fixes.
```

## Quick Checklist

- [ ] File starts with `# Title` (H1)
- [ ] Headings have space after `#`
- [ ] No heading level jumps
- [ ] No trailing whitespace
- [ ] Max 1 blank line between sections
- [ ] Lists use `-` consistently
- [ ] Code blocks have language specified
- [ ] Inline code uses backticks
- [ ] Links are properly formatted
- [ ] No bare URLs
- [ ] Lines under 120 chars where practical
- [ ] Bold uses `**text**`, italic uses `*text*`
- [ ] All section transitions are clear

## Common Violations to Avoid

❌ `#No space after hash`  
✓ `# Space after hash`

❌ `# Heading\n\n\n## Next` (two blank lines)  
✓ `# Heading\n\n## Next` (one blank line)

❌ `* or + for lists`  
✓ `- for all lists`

❌ Bare URL `http://example.com`  
✓ Wrapped URL `<http://example.com>`  
✓ Link `[text](http://example.com)`

❌ Indented code blocks  
✓ Fenced code blocks ` ``` `

❌ `# Skip to ### level`  
✓ `# Then ## Then ###`

❌ __emphasis with underscores__  
✓ **emphasis with asterisks**

## References

- [Markdownlint Rules](https://github.com/markdownlint/markdownlint/blob/main/README.md)
- [CommonMark Spec](https://spec.commonmark.org/)