Markdown Formatting for Cleaner PRs

Trailing spaces that GitHub paints red

The classic PR distraction. These lines look unchanged but the diff highlights trailing whitespace. Prettifying trims them so the next content change is the only thing that shows. (Trailing spaces shown as ·.)

Before (as committed):
Setup instructions are below.···
Run the installer.··

After (prettified):
Setup instructions are below.
Run the installer.

Heading edit no longer drags neighbours into the hunk

Without surrounding blank lines, editing a heading expands the diff to the lines above and below. Normalised spacing isolates the heading on its own.

Before:
The API is stable.
## Authentication
Use a bearer token.

After:
The API is stable.

## Authentication

Use a bearer token.

Whitespace-only commit, content untouched

Run the prettifier and the diff is purely spacing — no sentence, link, or code line changes. Reviewers can approve it without reading prose.

Before:
#  Release Notes


We shipped v2.

After:
#  Release Notes

We shipped v2.

(Only blank-line collapse applied; the heading text — including its
 double space after '#' — is preserved verbatim.)

Fixed-width wrap for minimal future diffs

Wrapping prose at 80 cols means a later edit to one sentence changes one line, not the whole paragraph. Choose 80 cols before committing.

Wrap width: 80 cols

Before (one line):
This section explains the rollback procedure and the on-call escalation path for production incidents.

After:
This section explains the rollback procedure and the on-call escalation path
for production incidents.

Code samples in the doc stay byte-for-byte

Reviewers trust that a formatting commit didn't quietly change a code example. The prettifier never touches fenced-block contents.

Before:
## Usage
```bash
npm run build    
  npm test
```
That's it.

After:
## Usage

```bash
npm run build    
  npm test
```

That's it.

If a doc has never been formatted, the first prettify can touch many lines. Land it as a standalone commit so subsequent PRs stay clean; reviewers approve the one-time pass and future diffs are small.

Trailing-whitespace trimming strips CommonMark two-space hard breaks. If a contributor relied on them, the rendered line breaks change. Prefer a trailing backslash (\) for breaks that survive prettifying — flag this in review.

The prettifier does not re-indent lists, so an inconsistently nested list still looks inconsistent in the source. If list hygiene matters for the PR, run the list fixer as a separate step.

Only prose lines are trimmed. Trailing spaces inside fences (e.g. a shell example) are kept, so the code sample in the PR is unchanged.

Only ATX (#) headings get blank lines added. A Setext heading underlined with ===/--- is treated as prose and stays as-is — convert to ATX if you want consistent heading spacing across the PR.

YAML/TOML frontmatter (common in static-site docs) is split off and re-attached verbatim. The reformat won't show up as a diff in the metadata block.

Mixing a prettify pass with a content edit in one commit reintroduces the noise problem. Keep formatting and content in separate commits so the review stays clean.

The output ends on the last content character; no final newline is appended. If your repo enforces a trailing newline (e.g. EditorConfig insert_final_newline), add it before committing or let your linter fix it.

Free is 1 MB / 500,000 chars per file. Big generated docs need Pro (10 MB / 5,000,000 chars) or higher. The character cap is independent of byte size.

HTML tags are treated as prose lines: trailing whitespace trimmed, blank-line rules applied around adjacent headings, but the tags themselves are never altered or removed.