# Markdown Formatter

> Format and clean up Markdown files. Fix heading levels, normalize lists, add table of contents, and ensure consistent style. Use when the user wants to format, lint, or clean up Markdown documents. Use when this capability is needed.

- Skill: `tomevault-io/markdown-formatter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/markdown-formatter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/markdown-formatter/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/markdown-formatter

---


# Markdown Formatter

Formats and cleans up Markdown files following consistent style rules.

## Features

- Fix heading hierarchy (no skipped levels)
- Normalize list markers (consistent `-` or `*`)
- Add or update table of contents
- Fix trailing whitespace
- Ensure files end with newline
- Format tables with aligned columns

## Usage

When the user asks to format a Markdown file:

1. Read the target file
2. Apply formatting rules
3. Write the formatted content back
4. Report what changed

### Formatting Rules

**Headings:**
- Ensure a single H1 at the top
- No skipped heading levels (H1 → H3 without H2)
- Add blank line before and after headings

**Lists:**
- Use `-` for unordered lists
- Use `1.` for ordered lists (auto-number)
- Indent nested lists with 2 spaces

**Code blocks:**
- Ensure language identifier on fenced blocks
- Use triple backticks (not tildes)

**Tables:**
- Align columns with padding
- Ensure header separator row exists

## Example

Input:
```markdown
# Title
### Skipped heading
* Mixed
- list
- markers
```

Output:
```markdown
# Title

## Skipped heading

- Mixed
- list
- markers
```

## Notes

- Always create a backup before modifying files
- Report the number of changes made
- Respect `.editorconfig` if present in the project

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kriskimmerle) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->