204 lines
4.2 KiB
Markdown
204 lines
4.2 KiB
Markdown
---
|
|
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: ``
|
|
- 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/)
|