Claude-skill-registry-data 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.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/markdown-formatting" ~/.claude/skills/majiayu000-claude-skill-registry-data-markdown-formatting && rm -rf "$T"

manifest: data/markdown-formatting/SKILL.md

source content

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
```
```
.markdownlintrc
```
```
markdownlint
```
key in
```
package.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 (
```
# 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

Links & Images

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.