How to format markdown for maximum readability
- Step 1Open the prettifier — Go to /markdown-tools/md-prettifier. The tool runs entirely in your browser — your draft is never uploaded to a server.
- Step 2Paste or drop your Markdown — Paste the source into the input, or drop a single
.md/.markdown/.mdxfile. The free tier handles up to 1 MB or 500,000 characters per file. - Step 3Choose a wrap width (or leave it off) — The only control is a Wrap width dropdown:
No wrap(default),80 cols,100 cols, or120 cols. Leave it onNo wrapif your editor or renderer handles soft-wrapping; pick a width if you want hard line breaks in the source. - Step 4Run the prettifier — Click Run. Heading spacing is normalised, trailing whitespace is trimmed, and triple blank lines are collapsed in a single pass.
- Step 5Compare the before/after — Skim the output: every heading now has one blank line above and below, gaps are uniform, and no line ends in stray spaces. The output keeps your original filename.
- Step 6Copy or download the result — Copy the prettified source back into your CMS / repo, or download the
.md. For deeper structural fixes, follow with a sibling tool (see the FAQs).
What the prettifier changes vs. leaves alone
Every transform is deterministic and spacing-only. Content (words, links, emphasis, code) is never rewritten.
| Aspect of the source | What happens | Why it matters for readability |
|---|---|---|
| Blank lines around a heading | Inserts exactly one blank line before and after each #..###### heading | A heading flush against its paragraph is hard to spot when scanning raw source |
| Trailing whitespace (prose lines) | Trimmed from every line outside code fences | Removes the · · · dots that clutter GitHub/GitLab diffs and trigger linters |
| Three-or-more blank lines in a row | Collapsed to a single blank line | Keeps vertical spacing uniform across a long, multi-author document |
| Leading blank lines at the top of the body | Stripped (trimStart) so the document starts on content (or right after frontmatter) | No dead space at the top of the file |
| Long prose paragraph | Hard-wrapped at the chosen width only if you select 80/100/120; off by default | Editors who prefer fixed-width source get clean wraps; everyone else keeps long lines |
| Words, links, emphasis, lists, code | Untouched — no content rewrite, no list re-indent, no paragraph reflow | Safe to run on a near-final draft without fear of a surprise edit |
Wrap-width dropdown
The wrap is greedy and word-based, applied to prose paragraphs only. It splits long lines; it does not re-join short ones.
| Dropdown choice | wrapWidth value | Effect on prose | Lines never wrapped |
|---|---|---|---|
| No wrap (default) | 0 | Long lines are left exactly as written | n/a — wrapping is off |
| 80 cols | 80 | Paragraphs hard-wrapped at 80 characters | Code fences, blank lines, list items (-,*,+,1.), table/heading lines |
| 100 cols | 100 | Paragraphs hard-wrapped at 100 characters | Same exclusions as above |
| 120 cols | 120 | Paragraphs hard-wrapped at 120 characters | Same exclusions as above |
Cookbook
Real before/after source from typical editorial Markdown. Notice the prettifier only moves whitespace — never a word.
Headings that touch their text get breathing room
The most common readability problem in hand-typed Markdown: a heading with no blank line above or below. The prettifier inserts exactly one of each.
Before: Intro sentence. ## Background The project began in 2024. ### Scope Three teams were involved. After: Intro sentence. ## Background The project began in 2024. ### Scope Three teams were involved.
Trailing whitespace removed from prose lines
Trailing spaces are invisible in the editor but show as red dots in diffs and trip markdownlint MD009. They are trimmed from every line outside code fences. (Trailing spaces shown here as ·.)
Before: The report covers Q1 and Q2.··· Results were mixed.·· After: The report covers Q1 and Q2. Results were mixed.
Stray triple blank lines collapsed to one
When sections get pasted and re-pasted, gaps grow to three or four blank lines in some places and one in others. The prettifier makes every gap a single blank line.
Before: End of section one. ## Section Two Text. After: End of section one. ## Section Two Text.
Optional 80-column wrap for fixed-width editors
If your house style is wrapped source (common for writers who diff in a terminal), pick 80 cols. The wrap is word-based and applies to prose only — lists and code are skipped.
Wrap width: 80 cols Before (one long line): This quarterly summary covers revenue, churn, and the three product launches that shipped between January and March of this year. After: This quarterly summary covers revenue, churn, and the three product launches that shipped between January and March of this year.
Code blocks pass through verbatim
Everything between fences is left exactly as-is — including indentation and trailing spaces inside the block. Only the prose around it is prettified.
Before: ## Example ```js const x = 1; const y = 2; ``` Done. After: ## Example ```js const x = 1; const y = 2; ``` Done.
Edge cases and what actually happens
YAML / TOML frontmatter at the top of the file
PreservedA leading ---...--- (YAML) or +++...+++ (TOML) block is split off and re-prepended byte-for-byte. None of the spacing rules touch it. The first heading in the body still gets a blank line after it, but not an extra one inserted before the frontmatter.
Setext headings (underlined with === or ---)
By design — not spacedThe heading-spacing rule matches only ATX headings (#..###### followed by a space). Setext-style headings (a line of text underlined by === or ---) are treated as ordinary prose, so no blank lines are inserted around them. Convert to ATX first if you want them spaced.
List items with irregular indentation
By design — left as writtenThe prettifier does not normalise list indentation. - item (three spaces after the marker) and a misaligned nested - child are left exactly as typed — only their trailing whitespace is trimmed. For consistent list markers and indentation, use the list-fixer instead.
Trailing whitespace inside a code block
PreservedTrailing spaces are trimmed only outside fenced code blocks. Inside fences, lines pass through verbatim — significant whitespace in code samples (e.g. Python, Makefiles) is never altered.
Markdown hard line break (two trailing spaces)
RemovedA line ending in two-or-more spaces is the CommonMark hard-break syntax. Because the prettifier trims trailing whitespace, those spaces are removed and the hard break is lost. If you rely on two-space hard breaks, use an explicit \ backslash line break or a real blank line instead.
A single very long prose line with No wrap selected
Expected — left longWith the default No wrap, a 4,000-character paragraph stays on one line. The prettifier only spaces and trims; wrapping is opt-in. Pick 80/100/120 cols if you want it broken up.
Paragraph already split across short lines, then wrapped
ExpectedThe wrap only splits lines that exceed the width — it does not re-join short lines into one paragraph first. A paragraph already broken into several short lines stays multi-line; each line is independently re-wrapped only if it is too long. For full reflow, join the paragraph before wrapping.
File larger than the free-tier limit
413 / blocked on freeFree tier caps at 1 MB or 500,000 characters per file. A larger manuscript needs Pro (10 MB / 5,000,000 chars) or higher. The character-count limit is separate from the byte limit — a dense ASCII file can hit 500,000 chars well before 1 MB.
Output has no trailing newline
ExpectedThe prettified body is trimStart-ed and the result ends on the last content character — no trailing newline is appended. If your repo convention requires a final newline (POSIX), add it after pasting, or run a linter that enforces MD047.
Inline HTML inside the Markdown
PreservedRaw HTML tags (<div>, <details>, <br>) are treated as ordinary prose lines: trailing whitespace is trimmed and surrounding blank-line rules apply, but the tags themselves are never modified or stripped.
Frequently asked questions
What exactly does the prettifier change?
Four things: one blank line before and after each ATX heading, trailing whitespace trimmed on prose lines, runs of three-or-more blank lines collapsed to one, and (only if you choose a wrap width) prose paragraphs hard-wrapped at 80/100/120 columns. Nothing else.
Will it change my actual words or links?
No. Content is preserved exactly — text, inline code, links, **bold**, *italic*, and lists come out byte-identical apart from trailing-whitespace trimming and the blank-line rules. It is a spacing tool, not a rewriter.
Does it reformat lists or fix indentation?
No. The prettifier does not normalise list indentation or markers — - item stays - item. For consistent list formatting use the list fixer.
Is the line wrap on by default?
No. The Wrap width dropdown defaults to No wrap. Long lines are left untouched unless you select 80, 100, or 120 cols.
What widths can I wrap at?
The dropdown offers No wrap, 80 cols, 100 cols, and 120 cols. The underlying option accepts any value from 0 to 200 via the API, but the UI exposes those four presets.
Does wrapping affect code blocks or lists?
No. Wrapping skips fenced code blocks, blank lines, list items (-,*,+,1.), and table/heading lines. Only ordinary prose paragraphs longer than the chosen width get broken.
How is this different from minifying?
Opposite intent. Prettify adds structure (blank lines around headings, optional wraps); the minifier removes structure (strips blank lines and whitespace for the smallest valid file). They are complementary.
Does it touch my frontmatter?
No. A leading YAML (---) or TOML (+++) frontmatter block is detected, split off, and re-attached unchanged. The spacing rules apply only to the document body below it.
Will it remove my two-space hard line breaks?
Yes — trailing whitespace is trimmed, so a CommonMark two-space hard break is removed. Use a trailing backslash (\) or a blank line for an intentional break that survives prettifying.
Does the file get uploaded anywhere?
No. The transform runs entirely in your browser. Your draft never reaches a server; only an anonymous processed-file counter is recorded for signed-in dashboard stats, which you can opt out of.
Can I run it as a pre-commit or CI step?
The web tool is interactive (paste or drop one file). For automation, the GET endpoint at the tool's URL returns its option schema, and execution is runner-backed via @jadapps/runner, which runs the markdown transform in-process locally so files never touch JAD servers.
What should I run after prettifying?
For rule-based hygiene, follow with the linter. To standardise emphasis markers, use the bold/italic cleaner. To repair misaligned tables, use table repair.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.