Skip to content
All posts

Format & Clean Up Messy Markdown: A Practical Tutorial (2026)

Turn inconsistent, hand-edited Markdown into clean, consistent documents — normalize whitespace, bullets, and headings with a formatter, and build perfect tables with a visual generator.

Markdown is forgiving, which is exactly why it gets messy. Mixed bullet characters, inconsistent heading spacing, trailing whitespace, ragged tables, and stray blank lines accumulate as documents pass through different hands and editors. This tutorial shows how to clean it all up with two tools: the Markdown formatter for whole-document normalization, and the table generator for tables that actually line up.

Why formatting matters

Inconsistent Markdown causes real problems:

  • Noisy diffs — whitespace-only changes bury real edits in code review.
  • Rendering surprises — a missing space after # means ##Heading doesn't render as a heading.
  • Portability bugs — some parsers are stricter than others; clean Markdown travels best.
  • Looks unmaintained — ragged tables and mixed bullets signal neglect.

Formatting is the Prettier of Markdown: pick a consistent style and apply it automatically.

Part 1: The formatter

The Markdown formatter normalizes a whole document and flags issues with auto-fix.

What it fixes

IssueBeforeAfter
Mixed bullets* a / + b / - c- a / - b / - c
Heading spacing##Title## Title
Trailing whitespacetext text
Multiple blank lines3+ blank linessingle blank line
Inconsistent task markers- [X] / - [ ]normalized

Workflow

  1. Paste your messy Markdown into the formatter.
  2. Review the flagged lint issues.
  3. Apply auto-fix and copy the clean result.

The built-in linter is the same conservative ruleset behind the validate API — so what you fix here is what CI would flag (see Lint Markdown in CI).

Bullet style: pick one

Markdown allows -, *, and + for bullets. Mixing them is the most common inconsistency. The formatter (and the dedicated list normalizer) converts everything to - while skipping fenced code blocks so your code snippets stay untouched.

Part 2: Tables that line up

Hand-written Markdown tables are painful — one wrong pipe and the whole table breaks. The table generator gives you a spreadsheet-style UI:

  1. Set rows and columns.
  2. Type cell content.
  3. Pick alignment per column (left / center / right).
  4. Copy clean GFM, ready to paste.

Alignment syntax

The generator produces the alignment row for you, but it helps to know it:

| Left | Center | Right |
| :--- | :----: | ----: |
| a    | b      | c     |
  • :--- left, :---: center, ---: right.
  • Keep cells non-empty (N/A beats blank) — some renderers and accessibility linters dislike empty cells.

For existing tables that need restructuring (sort, transpose, reorder columns), use the table transformer; to convert spreadsheet data, use the CSV/TSV ↔ table tool. See the table guide for advanced patterns.

A complete cleanup pass

Inheriting a neglected doc? Run this sequence:

  1. Format the whole document — formatter.
  2. Normalize lists if bullets are mixed — list normalizer.
  3. Fix headings — check hierarchy with the heading audit.
  4. Rebuild broken tables — table generator.
  5. Tidy typography — smart quotes/dashes with the typography cleaner.
  6. Verify — link checker and GFM checklist.

The document goes from "edited by ten people over two years" to "looks like one careful author wrote it."

Automating formatting

For pipelines and bulk cleanup:

JobEndpoint
Format/normalize/api/v1/format
Validate (lint only)/api/v1/validate
Normalize lists/api/v1/transform/normalize-lists
Typography/api/v1/transform/typography

Run format in a pre-commit hook so every committed .md is consistent — the same idea as the pull-request lint setup, but auto-fixing instead of just flagging.

Common cleanup mistakes

1. Normalizing inside code blocks. Never reformat fenced code — the formatter and list normalizer skip fences for exactly this reason.

2. Empty table cells. Use N/A; blank cells trip some renderers and a11y linters.

3. Reformatting without reviewing. Auto-fix is safe, but skim the diff — especially on intentional formatting.

4. Forgetting typography. Smart quotes and em dashes pasted from Word can break code or look inconsistent — clean them with the typography cleaner.

5. Skipping the heading check. Formatting fixes spacing, not hierarchy — run the heading audit separately.

Quick reference

JobTool
Normalize documentFormatter
Unify bulletsList normalizer
Build tablesTable generator
Restructure tablesTable transformer
Fix quotes/dashesTypography cleaner

Clean Markdown is a one-click habit, not a chore. Run the formatter before you commit, build tables with the generator, and your documents read like a single careful author wrote them.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.