Markdown Formatter

Markdown renders anything. That is the problem.

A Markdown file has no compiler shouting at you. Write a bullet with a star on one line, a dash on the next, indent a sublist by three spaces, and every renderer still produces something. The output looks fine. The file is a mess, and the mess only surfaces when a teammate reformats it in their editor and the pull request shows 240 changed lines for a two word fix. This page settles those choices in one pass so the next diff shows the edit instead of the whitespace.

Project Falcon
==============
##Install
* npm i falcon-queue
* npx falcon init
1. Start the worker
1. Point it at redis

# Project Falcon
## Install
- npm i falcon-queue
- npx falcon init
1. Start the worker
2. Point it at redis

Formatting is half of what happens when you press Format. The panel above also reads the document structure and reports what it finds: how the heading levels step, whether two headings collide on the same anchor slug, which images ship without alt text, how many URLs are sitting in the text as bare strings. Those are the defects that survive a proofread because nothing about them looks wrong on screen.

List indentation is where files quietly split in two

The nesting rule in CommonMark is stricter than most people write. A child list has to be indented to the point where the parent item's content starts, not by some fixed number of spaces. Under a dash bullet the marker is two characters wide, so the child needs two spaces. Under 10. the marker is four characters wide, so the child needs four.

The formatter reads your original indent depth to work out which level each item belongs to, then rewrites every level from scratch using the width of its own parent marker. Hand written files usually come back one or two spaces narrower per level, which is the point. What you get is nesting no parser has to guess at.

Two heading syntaxes, one of which turns into a horizontal rule

Markdown supports setext headings, written by underlining a line with equals signs or dashes. They look tidy in a plain text editor and they carry a trap: a setext underline made of dashes is one blank line away from being a thematic break.

Release notes
-------------
Release notes
-------------

The first pair is an H2. The second is a paragraph followed by a horizontal rule, because the blank line ended the paragraph before the dashes arrived. Delete a line by accident and your section heading becomes decoration. Everything here converts to ATX form, the hash prefix style, which has no positional dependency at all. Closing hashes are stripped, missing spaces after the hashes are added, and stray indentation before them is removed.

Table pipes are the one alignment that changes meaning

Whitespace inside a Markdown table is ignored by the renderer, with one exception. The colons in the delimiter row set column alignment, and they are easy to get wrong when the row is written by hand.

Alignment is read from the delimiter row, then every cell is padded so the source columns line up on screen. Escaped pipes and pipes inside backtick spans are left alone, since those belong to the cell content rather than the structure. Turn the checkbox off when a table has one wide prose column, because padding to that width makes the source worse rather than better.

Hard breaks are two invisible spaces

A line break inside a paragraph is written as two trailing spaces. Nothing shows them. Editors strip trailing whitespace on save, linters flag them as errors, and reviewers delete them without noticing, at which point an address block collapses into one run-on line. The other spelling is a trailing backslash, which is visible, survives every save hook, and is supported by CommonMark.

The Hard breaks control decides which form your document uses. Keep spaces preserves what you wrote, Backslash rewrites every hard break in the visible form, and Drop removes them so paragraphs reflow. Any trailing whitespace that was not acting as a break is removed either way.

What the report flags while it formats

• Heading level jumps. An H2 followed by an H4 reads as a missing section to anything building a document tree, including screen readers and every table of contents generator. The report names the heading where the jump happens.
• Duplicate anchor slugs. Two sections called Risks both want the anchor #risks. GitHub appends a suffix to the second one, so a link to #risks lands on the wrong section, and the suffix rule differs on other platforms.
• Images with empty alt text. Written as an exclamation mark then empty brackets, the image is invisible to anyone using assistive tech and contributes nothing when the file is indexed.
• Bare URLs. GitHub autolinks plain URLs, CommonMark does not. Angle brackets around the URL make it work in both.
• Unclosed code fences. One missing fence turns the rest of the document into a code block. The preview shows this instantly, the report says why.
• Tab indentation and indented code blocks. Tab width is undefined in Markdown, so tabbed nesting shifts between renderers. Indented code blocks break as soon as someone reindents the list above them.

Where this page stops

• It formats, it does not convert. Output is still Markdown. For HTML use the Markdown to HTML converter, and for the opposite direction use HTML to Markdown.
• Front matter is treated as content. A YAML block at the top of the file is not parsed as metadata, so dashes and colons inside it may be reformatted. Cut it out before formatting a Jekyll or Hugo page, or check the top of the output before saving.
• MDX and JSX inside Markdown are out of scope. Component tags survive as text but their attributes are not understood. Use the MDX formatter for those files.
• Reference style links keep their definitions where they are. Labels are not renumbered and definition blocks are not moved to the foot of the document.
• Deliberate blank line grouping inside blocks is lost. Whitespace is rebuilt rather than adjusted. Runs of blank lines collapse to one and a blank line is inserted before every heading.
• The preview is one renderer, not yours. It follows GitHub Flavored Markdown. A docs site running its own extensions, footnotes, admonitions, math blocks, will show more than this preview does.