4.2 KiB
4.2 KiB
name, description, applyTo
| name | description | applyTo | |
|---|---|---|---|
| markdown-linting | Markdown formatting standards following markdownlint practices |
|
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.(always1.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
# Main Title
Brief introduction (1-2 sentences).
## Section One
Content here.
### Subsection
Details.
## Section Two
More content.
## See Also
- [Link text](url)
API Documentation
# API Endpoint Name
Brief description.
## Overview
What this does.
## Prerequisites
- Prerequisite 1
- Prerequisite 2
## Usage
### Request
```bash
curl command
Response
json example
Configuration
- Option 1: description
- Option 2: description
Troubleshooting
Problem
Solution.
See Also
### 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