Markdown Formatter
Beautify Markdown, normalize headings, lists, and code blocks.
Markdown Input
Formatted
Waiting for input
What is Markdown Formatter?
A Markdown formatter is a tool that parses a Markdown document and re-emits it with normalized heading syntax, list markers, code fences, and link reference layouts so the source matches a consistent style and renders identically across every Markdown engine. The rendered output stays the same. The source becomes diff-friendly.
Technical writers, open-source maintainers, and developer relations engineers reach for a Markdown formatter when a README has drifted across contributors, when a docs site shows inconsistent heading styles, or when a pull request diff is unreadable because mixed bullet markers and ATX vs Setext headings collide. Formatting flattens the document to a single canonical form so the next contributor inherits a clean baseline.
Why use a Markdown formatter?
- Force one heading style. ATX headings (
# Heading) and Setext headings (Heading\n=======) render the same but diff differently. Normalizing to ATX collapses the noise so changes are visible at a glance. - Standardize list markers. Mixing
*,-, and+for unordered lists is legal Markdown but visually chaotic. A formatter picks one (typically-) and applies it everywhere. - Reflow tables and fences. GitHub Flavored Markdown tables drift out of column alignment as cells are edited. Reformatting recomputes pipe padding so the source table is as readable as the rendered output.
- Catch broken syntax. A formatter that parses the document rejects malformed link references, unbalanced emphasis, and unclosed code fences. These errors render silently in most viewers but surface immediately under a strict parser.
- Shrink pull request diffs. Whitespace changes from a chat-app copy-paste vanish after formatting, so the diff shows only the prose or code that actually changed.
How to use the Markdown Formatter
- Paste your Markdown into the Input panel. The formatter accepts CommonMark and GitHub Flavored Markdown (GFM), including tables, task lists, and strikethrough.
- Click Format. The document is parsed and re-emitted with normalized syntax.
- Read the rewritten document in the Output panel. Parse errors appear above the input panel with a line reference.
- Click Copy to copy the formatted Markdown to your clipboard, then paste it back into your README, docs page, or pull request.
Markdown formatting rules
The formatter applies the conventions in the CommonMark spec plus the GitHub Flavored Markdown extensions, matched by Prettier and markdownlint defaults.
| Element | Convention | Why |
|---|---|---|
| Headings | ATX style (# H1) | Diffs cleaner than Setext |
| Bullet markers | - for unordered lists | Most common across major styleguides |
| Ordered lists | 1. then 2. (incremented) | Renders correctly even if a list item is reordered |
| Bold | **bold** not __bold__ | Avoids collision with intra-word underscores |
| Italic | _italic_ not *italic* | Disambiguates from bold and list markers |
| Code fences | Triple backticks with language tag | Enables syntax highlighting |
| Tables | Pipes padded to align columns | Source matches rendered alignment |
| Link references | Grouped at the document end | Keeps body prose readable |
| Hard line breaks | Two trailing spaces or \ | CommonMark-compliant |
| Trailing whitespace | Stripped | Prevents accidental hard breaks |
Examples
A README with mixed bullet markers, inconsistent headings, and an unaligned table:
Project Name
============
## Features
* Fast install
+ Zero config
- Works offline
## Install
```sh
npm i project| Command | Description |
|---|---|
start | Run dev server |
build | Produce a production bundle |
test | Run the test suite |
After formatting, headings, bullets, and tables follow one convention:
```markdown
# Project Name
## Features
- Fast install
- Zero config
- Works offline
## Install
```sh
npm i project| Command | Description |
|---|---|
start | Run dev server |
build | Produce a production bundle |
test | Run the test suite |
## Markdown Formatter vs alternatives
The right Markdown formatter depends on whether you are editing one file in a browser or hundreds of files in a repo.
| Tool | Best for | Offline | Cost | Limitations |
|---|---|---|---|---|
| In-browser Markdown formatter | Single document pulled from chat or email | No | Free | No file watch, no save-on-format |
| `prettier --write '**/*.md'` | Formatting Markdown across a repo | Yes | Free | Requires Node.js setup |
| `markdownlint --fix` | Lint plus auto-fix in CI | Yes | Free | Stricter than Prettier, may reject valid GFM |
| VS Code Markdown All in One | Live formatting while editing | Yes | Free | IDE-bound, not portable |
For one-off cleanup of a Slack message or a chat-app paste, an in-browser Markdown formatter is the fastest path. For consistent style across a docs repo, wire `prettier` or `markdownlint --fix` into pre-commit hooks.
## Common use cases
- **Open-source maintainers** cleaning up README and CONTRIBUTING files when a contributor drops in unformatted content from a chat thread.
- **Technical writers** unifying heading style and link reference layout across a large Nextra, Docusaurus, or VitePress documentation site.
- **Developer advocates** formatting blog post drafts copied from Notion, Google Docs, or Linear before publishing.
- **Engineering teams** normalizing pull request templates and issue templates so every team uses the same Markdown conventions.
- **Educators** preparing technical course materials in `.md` files for GitHub Classroom or MkDocs.
## Frequently asked questions
### What is the difference between CommonMark and GitHub Flavored Markdown?
CommonMark is the standardized core specification for Markdown. GitHub Flavored Markdown (GFM) is a superset that adds tables, task lists, strikethrough, autolinks, and fenced code blocks with language tags. The Markdown formatter handles both and preserves GFM features when present. Render targets that only support CommonMark may drop the extras.
### Does the formatter change my rendered output?
It should not. Every transformation is structural, not semantic. Bold renders as bold whether the source uses `**` or `__`. The rendered HTML is byte-identical for almost every input. The rare exception is when the original source was ambiguous and the formatter picks a canonical interpretation.
### Why are my links reformatted as references?
Long inline links bloat paragraphs and obscure prose. Some Markdown style guides move every link to a numbered reference at the end of the document, so the body reads as clean text. This formatter preserves inline links by default but supports reference-style output through the reference option.
### Will it preserve front matter?
Yes. YAML front matter delimited by `---` at the top of the document is passed through untouched. TOML front matter delimited by `+++` is also preserved. Front matter blocks are common in Hugo, Jekyll, Astro, and Next.js MDX content.
### How does it handle MDX or JSX inside Markdown?
The formatter is CommonMark plus GFM. It does not parse JSX expressions or MDX-specific syntax. JSX blocks pass through as raw text. For MDX files, use Prettier with the `@prettier/plugin-mdx` plugin or the MDX-aware formatter built into your editor.
### Can it format Markdown tables?
Yes. GFM tables are parsed, column widths are recomputed from the longest cell, and pipe padding is added so each column aligns in the source. Empty cells are filled with a single space.
### Does it strip HTML?
No. Raw HTML embedded in Markdown is preserved. Self-closing tags, `<br>`, `<details>`, and `<summary>` are common in READMEs and stay in place after formatting. If you want HTML removed, use a separate strip-HTML tool.
### Will the formatter add a table of contents?
No. Generating a TOC is the job of the renderer (GitHub auto-generates one for long READMEs) or a dedicated plugin like `markdown-toc`. The formatter only reformats existing content.
## Related tools
- [YAML Formatter](/tools/yaml-formatter) - clean up YAML manifests and front matter blocks.
- [SQL Formatter & Beautifier](/tools/sql-formatter) - pretty-print SQL queries with standard keyword casing.
- [TypeScript Formatter](/tools/typescript-formatter) - apply Prettier defaults to TypeScript source files.
- [HTML Prettify](/tools/html-prettify) - format raw HTML blocks pulled out of a Markdown document.Related tools
Like this tool?
ShotMark captures what you do here, in one click.
The traces, payloads, and tests you run by hand? ShotMark grabs the whole bug and hands it to your AI agent.
Private beta accessFounding pricing lockNo spam ever