markdown-formatting
Format and lint markdown and MDX files using markdownlint with comprehensive rule knowledge for automated and manual fixes. Use when working with .md or .mdx files, formatting documentation, linting markdown/MDX, or when user mentions markdown issues, formatting problems, or documentation standards.
When & Why to Use This Skill
This Claude skill automates the formatting and linting of Markdown and MDX files using markdownlint. It ensures documentation consistency by enforcing standardized rules for headings, lists, whitespace, and syntax, allowing users to identify and fix issues automatically or manually to maintain high-quality technical documentation.
Use Cases
- 1. Documentation Standardization: Enforce consistent heading hierarchies, list markers, and spacing across large documentation projects to ensure a professional look.
- 2. Automated Quality Assurance: Use as a part of the development workflow to identify syntax errors, broken link formats, or missing alt text in images before publishing.
- 3. MDX Structure Validation: Maintain clean and error-free MDX files for modern documentation frameworks like Docusaurus, Nextra, or Gatsby.
- 4. Legacy Content Refactoring: Quickly clean up inherited documentation folders by removing trailing spaces, fixing tab/space inconsistencies, and standardizing code block languages.
| name | markdown-formatting |
|---|---|
| description | Format and lint markdown and MDX files using markdownlint with comprehensive rule knowledge for automated and manual fixes. Use when working with .md or .mdx files, formatting documentation, linting markdown/MDX, or when user mentions markdown issues, formatting problems, or documentation standards. |
Markdown & MDX Formatting & Linting
Format and lint markdown and MDX files using markdownlint CLI tools with comprehensive understanding of all markdown rules.
Quick Start
# Check if markdownlint is available
which markdownlint || which markdownlint
# Install if needed
pnpm add -D markdownlint
# or
npm install -g markdownlint
# Auto-fix files (markdown and MDX)
markdownlint --fix "**/*.{md,mdx}"
# Check specific files
markdownlint README.md docs/**/*.md content/**/*.mdx
Configuration Detection
Check for config files in this order:
.markdownlint.json.markdownlint.jsonc.markdownlint.yaml.markdownlintrcmarkdownlintkey inpackage.json
Common Workflow
- Detect environment: Check for markdownlint CLI
- Find config: Look for config files
- Run linter: Identify issues
- Apply fixes: Auto-fix or manual
- Verify: Re-run to confirm
Most Common Issues & Quick Fixes
Headings
- MD001: Heading levels increment (# → ## → ### not # → ###)
- MD018/MD019: Single space after hash (
# Headingnot#Heading) - MD022: Blank lines around headings
- MD025: Single H1 per document
- MD041: First line should be H1
<!-- Good heading structure -->
# Main Title
## Section
### Subsection
Content here...
Lists
- MD004: Consistent list markers (all
-or all*) - MD007: Nested lists indent 2 spaces
- MD030: Single space after list marker
- MD032: Blank lines around lists
<!-- Good list structure -->
- Item 1
- Nested item
- Another nested
- Item 2
Whitespace
- MD009: No trailing spaces
- MD010: Use spaces not tabs
- MD012: Single blank lines (not multiple)
- MD047: File ends with newline
Links & Images
- MD034: Wrap bare URLs in
<>:<http://example.com> - MD042: Links need text:
[Link Text](url)not[](url) - MD045: Images need alt text:

Code Blocks
- MD031: Blank lines around code blocks
- MD040: Specify language for code blocks
<!-- Good code block -->
Text before
```javascript
const code = 'here';
```
Text after
CLI Commands
# Fix all markdown and MDX files
markdownlint --fix "**/*.{md,mdx}"
# Fix specific files
markdownlint --fix README.md CHANGELOG.md content/blog.mdx
# Check without fixing
markdownlint "**/*.{md,mdx}"
# Use specific config
markdownlint --config .markdownlint.json "**/*.{md,mdx}"
# Ignore specific rules
markdownlint --disable MD013 MD033 "**/*.{md,mdx}"
# Output JSON for parsing
markdownlint --json "**/*.{md,mdx}"
Common Patterns
Fix Multiple Issues at Once
<!-- Before -->
#Title
Some text with trailing spaces
Tab indented line
- Item 1
* Item 2
Visit http://example.com
<!-- After -->
# Title
Some text with trailing spaces
Space indented line
- Item 1
- Item 2
Visit <http://example.com>
Add to package.json
{
"scripts": {
"lint:md": "markdownlint \"**/*.{md,mdx}\" --ignore node_modules",
"lint:md:fix": "markdownlint \"**/*.{md,mdx}\" --ignore node_modules --fix"
}
}
Detailed Rules Reference
For comprehensive documentation of all markdown rules with examples and fixes, see rules-reference.md.