How to team-wide markdown formatting
- Step 1Agree on the team standard — Decide one Wrap width for all docs:
No wrap(let the renderer soft-wrap) or a fixed80/100/120 cols. Write it into your contributing guide. - Step 2Open the prettifier — Send teammates to /markdown-tools/md-prettifier. It's browser-based, so there's nothing to install and everyone runs the same logic.
- Step 3Drop a contributor's doc — Paste the source or drop one
.mdfile. Free handles 1 MB / 500,000 characters; Pro raises it to 10 MB / 5,000,000 chars and allows batches of up to 10 files. - Step 4Apply the agreed wrap width — Set the Wrap width dropdown to the team standard you codified, so every doc converges to the same line shape.
- Step 5Run and merge — Click Run; heading spacing, trailing whitespace, and blank-line runs are normalised. The output keeps the original filename for an easy drop-back into the repo.
- Step 6Make it part of the writing process — Have contributors prettify before opening a docs PR, so drift never accumulates again. Combine with the linter for rule-level checks.
Multi-author drift vs. the normalised baseline
Whatever spacing style a contributor's editor produces, the prettifier maps it to one deterministic shape.
| Drift you see across authors | Cause | Normalised result |
|---|---|---|
| Some headings spaced, some flush | Different editors / manual typing habits | Exactly one blank line before and after every ATX heading |
| Trailing whitespace on random lines | Editors that don't trim on save | Trimmed from all prose lines (code fences excluded) |
| Gaps of 1–4 blank lines | Copy-paste between sections / merge artifacts | Every gap collapsed to a single blank line |
| Mixed line widths (some wrapped, some not) | Per-author editor wrap settings | Converge to your one team wrap width (or No wrap) |
| Leading blank lines at file start | Templates / paste artifacts | Stripped from the body; frontmatter preserved |
| Differing list indentation | Per-editor list behaviour | Left as-is — use the list fixer for this (not in scope here) |
Tier limits for team-scale formatting
The markdown family's limits. charLimit is a separate cap from file size — a dense file can hit it before the byte limit.
| Tier | Max file size | Max characters / file | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10 |
| Pro-media | 50 MB | 20,000,000 | 50 |
| Developer | 500 MB | Unlimited | Unlimited |
Cookbook
Each example takes source as a different teammate might have written it and shows the single normalised result.
Author A: headings flush against text
One contributor never adds blank lines around headings. The prettifier inserts exactly one before and after each.
Before (Author A): Overview text. ## Goals Ship by Q3. ## Risks Vendor lock-in. After (normalised): Overview text. ## Goals Ship by Q3. ## Risks Vendor lock-in.
Author B: trailing whitespace everywhere
Another teammate's editor leaves trailing spaces on every line. They're trimmed from prose without touching content. (Trailing spaces shown as ·.)
Before (Author B): ## Goals·· Ship by Q3.··· After (normalised): ## Goals Ship by Q3.
Author C: four blank lines between sections
Big vertical gaps from copy-paste collapse to a single blank line, matching the team baseline.
Before (Author C): ## Risks Vendor lock-in. ## Mitigations Dual-source the API. After: ## Risks Vendor lock-in. ## Mitigations Dual-source the API.
Team standard: wrap all docs at 100 cols
Your contributing guide says 100-column source. Everyone sets the dropdown to 100 cols, and prose converges to the same line shape.
Wrap width: 100 cols Before (Author D, one long line): The onboarding runbook covers laptop provisioning, repository access, the staging environment, and the first-week pairing schedule for new engineers. After: The onboarding runbook covers laptop provisioning, repository access, the staging environment, and the first-week pairing schedule for new engineers.
Docs-as-code page with frontmatter
A static-site docs page keeps its YAML frontmatter untouched; only the body is normalised.
Before: --- title: Runbook weight: 3 --- # Runbook Follow the steps below. After: --- title: Runbook weight: 3 --- # Runbook Follow the steps below.
Edge cases and what actually happens
List indentation differs between authors
By design — out of scopeThe prettifier does not normalise list markers or indentation, so author-specific list styles survive. Pair it with the list fixer if your standard also covers lists.
Emphasis markers differ (_x_ vs *x*) across the team
By design — out of scopeThe prettifier leaves */_ emphasis markers exactly as written. To standardise them team-wide, run the bold/italic cleaner.
A teammate relied on two-space hard breaks
RemovedTrailing-whitespace trimming removes CommonMark two-space hard breaks, which can change how their lines render. Standardise on a trailing backslash (\) or blank lines in the contributing guide.
Setext headings from an older author
By designOnly ATX headings get spaced. Underline-style (Setext) headings are treated as prose. If your standard is ATX, ask authors to convert; the prettifier won't do it for them.
Frontmatter blocks across many pages
PreservedEvery page's YAML/TOML frontmatter is detected and re-attached unchanged, so a team-wide normalisation pass won't churn the metadata of a docs site.
Batch-normalising many files at once
Pro featureThe free tier processes one file per run. Pro allows up to 10 files, Pro-media 50, and Developer is unlimited — useful when normalising a whole docs folder in one go.
Code blocks contributed with significant whitespace
PreservedTrailing whitespace inside fences is kept, so a teammate's indentation-sensitive code sample (Python, YAML) is never altered by the standard.
Output lacks a final newline
ExpectedThe result ends on the last content character. If your repo's EditorConfig enforces a final newline, configure your editor or linter to add it after the normalisation pass.
A very large generated doc exceeds the tier cap
413 / blocked on freeFree is 1 MB / 500,000 chars. Generated API docs often exceed that; move the team to Pro or higher. The 500,000-character cap is independent of the 1 MB byte cap.
Inline HTML used by some authors
PreservedRaw HTML (e.g. <div class="note">) is treated as prose: trimmed and spaced around adjacent headings, but never modified or stripped, so author HTML conventions survive normalisation.
Frequently asked questions
How does this keep team docs consistent?
It's deterministic: the same source always produces the same spacing. Run it on any contributor's file and you get one baseline — one blank line around headings, no trailing whitespace, single blank-line gaps.
Is it safe to mandate across the whole team?
Yes. The transform is content-safe — it never rewrites words, links, emphasis, lists, or code, so a team-wide normalisation pass can't introduce a stealth content change.
Does every teammate need to install anything?
No. It runs in the browser, so everyone uses the identical implementation with zero local setup — no Node, no Prettier config to sync.
Should we wrap or not wrap as a team?
Pick one and codify it. No wrap is simplest if your renderer soft-wraps; a fixed 80/100/120 gives stable source lines. The key is that everyone uses the same setting.
Can we normalise a whole folder of docs at once?
Free is one file per run. Pro allows batches of up to 10 files, Pro-media 50, Developer unlimited — so a docs folder can be normalised in fewer passes on a paid tier.
Will it standardise our list style too?
No. List indentation and markers are out of scope here. Add the list fixer to your team workflow for that.
What about consistent bold/italic markers?
Also out of scope. Use the bold/italic cleaner to standardise */_ and **/__ across the team.
Does it preserve frontmatter on every page?
Yes. YAML (---) and TOML (+++) frontmatter is split off and re-attached byte-for-byte, so a normalisation pass won't churn metadata across a docs site.
How large can a team doc be?
Free: 1 MB / 500,000 characters per file. Pro: 10 MB / 5,000,000. Pro-media: 50 MB / 20,000,000. Developer: 500 MB / unlimited. The character cap is separate from byte size.
Is anything uploaded to a server?
No. Processing is in-browser; team docs never reach JAD servers. Only an anonymous processed-file counter is kept for signed-in dashboards, and it's optional.
Can we automate this in our docs CI?
The web tool is interactive. For automation, the tool's GET endpoint exposes its schema, and execution is runner-backed via @jadapps/runner, which runs the markdown transform in-process locally so files never leave your environment.
What should we run alongside it for full hygiene?
Pair it with the linter for rule checks, the list fixer for lists, and table repair for tables.
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.