Markdown Formatter

How the Markdown Formatter works

Markdown is forgiving. The same heading can be written with hashes or an underline, a bullet can start with a hyphen, an asterisk or a plus sign, and a list numbered 1, 1, 1 renders the same as 1, 2, 3. That freedom is pleasant while writing and messy when several people edit the same README or docs site, because every edit produces a noisy diff and the source becomes hard to read.

What the Markdown formatter changes

The tool walks the document line by line and applies a small set of rules taken from common style guides such as markdownlint's defaults:

• Headings. Setext headings, a line underlined with === or ---, become # and ##. Closing hashes are removed and one space follows the opening hashes. Each heading gets a blank line above and below.
• Bullets. Every unordered item uses the marker you choose, keeping its indentation so nested lists stay nested.
• Ordered lists. Items are renumbered from the list's first number, or all set to that first number if you prefer.
• Tables. Cells are padded so the pipes line up, with alignment colons preserved and right-aligned columns padded on the left.
• Rules. Thematic breaks such as *** or _ _ _ become ---.
• Whitespace. Trailing spaces go, runs of blank lines collapse to one, and the file ends with a single newline.

Lines Changed counts how many lines differ from the input, which is a quick way to judge whether a pull request will be mostly formatting noise.

What it deliberately leaves alone

Anything inside a fenced code block, opened with three or more backticks or tildes, is copied exactly, including indentation and trailing spaces. Inline code, links, emphasis and HTML are not rewritten. The formatter does not wrap or unwrap long paragraphs either, because reflowing prose changes every line in a diff and breaks the one-sentence-per-line style some teams use.

Two trailing spaces at the end of a line are a hard line break in CommonMark, so the tool keeps exactly two when they sit before another line of text. Everywhere else trailing whitespace is removed.

Sequential or all the same number

Both styles render identically, because Markdown only uses the first number of a list as its start value. Sequential numbering reads better in the raw file. Numbering every item 1. means inserting or reordering items never forces you to renumber the rest, which keeps diffs small. Pick one style per project and stick to it.

A list that starts at a number other than 1 keeps its start. The formatter only adds a blank line before an ordered list that starts at 1, because CommonMark lets only such a list interrupt a paragraph; adding one before 3. would turn a sentence into a list.

Choosing a bullet marker

The hyphen is the most common choice and the default in Prettier and most linters. The asterisk is also widespread but is easy to confuse with emphasis when a bullet starts with bold text. The plus sign is valid but rare. Whichever you choose, consistency matters more than the character: mixing markers in one list can split it into several lists in some renderers.

Why align tables

Aligned pipe tables are much easier to read and edit in a plain text editor, and reviewers can see a changed cell at a glance. The cost is that editing one wide cell can shift a whole column, which widens diffs. If your team edits tables often, Leave as is keeps the original spacing and only strips trailing whitespace.

Before you commit

Run the formatted text through your usual preview once. Markdown flavours differ at the edges: GitHub, GitLab, Pandoc and static site generators each add extensions such as task lists, footnotes and definition lists. The formatter only touches constructs common to all of them, but a quick look catches the rare document that relied on unusual spacing to render the way it did.

Related tools