markdown-formatting

denolfe's avatarfrom denolfe

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.

⭐79stars🔀6forks📁View on GitHub🕐Updated Dec 30, 2025⬇️2downloads

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.
namemarkdown-formatting
descriptionFormat 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:

  1. .markdownlint.json
  2. .markdownlint.jsonc
  3. .markdownlint.yaml
  4. .markdownlintrc
  5. markdownlint key in package.json

Common Workflow

  1. Detect environment: Check for markdownlint CLI
  2. Find config: Look for config files
  3. Run linter: Identify issues
  4. Apply fixes: Auto-fix or manual
  5. Verify: Re-run to confirm

Most Common Issues & Quick Fixes

Headings

  • MD001: Heading levels increment (# → ## → ### not # → ###)
  • MD018/MD019: Single space after hash (# Heading not #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
  • MD034: Wrap bare URLs in <>: <http://example.com>
  • MD042: Links need text: [Link Text](url) not [](url)
  • MD045: Images need alt text: ![Description](image.png)

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.

Resources