Markdown Formatter

Markdown is readable source, so source layout matters

Markdown often serves two audiences: a renderer turns it into HTML, while contributors read and edit the plain text. The Markdown Formatter improves that source view by standardizing unordered-list markers, normalizing ATX heading spacing, aligning pipe tables, cleaning block quote spacing, and optionally wrapping ordinary text at 80 characters. Input and output remain side by side, and the result can be copied or downloaded as formatted.md.

Unlike a generic whitespace cleanup, the formatter protects fenced code blocks. Lines between matching triple-backtick or triple-tilde fences pass through unchanged, preventing example indentation and code syntax from being reformatted as prose. The surrounding Markdown still needs review because dialects and extensions differ across GitHub, documentation engines, static-site generators, and note applications.

A mixed-document example

Start with inconsistent source:

##Release checklist

* Build the package
+  Publish the artifact

|Stage|Owner|Required|
|---|:---:|---:|
|Build|CI|yes|
|Deploy|Ops|yes|

>Remember to verify the checksum.

With hyphen bullets, table alignment, and heading spacing enabled, output becomes:

## Release checklist

- Build the package
- Publish the artifact

| Stage  | Owner | Required |
| ------ | :---: | -------: |
| Build  | CI    | yes      |
| Deploy | Ops   | yes      |

> Remember to verify the checksum.

Alignment markers in the divider row are retained while dashes expand to the calculated column width. Each column is at least three characters wide. Cell text is padded so the pipes line up in a monospace editor.

Four controls, four separate decisions

List Bullet converts recognized unordered items to -, *, or +. Recognition requires a marker followed by whitespace. Existing leading spaces are preserved, so nested list indentation remains available. Task-list text such as [ ] or [x] remains part of the item content. Ordered-list numbers are retained rather than renumbered.

Align Tables collects consecutive trimmed lines that begin with |, splits their cells on unescaped pipes, calculates widths from non-divider rows, and rebuilds the table. Escaped \| sequences are protected during splitting. Disable this option when a dialect does not use leading pipes or when cell content contains syntax too complex for simple pipe handling.

Header Spacing turns ###Title into ### Title. Disabling it removes the gap instead. Any trimmed line beginning with one or more # characters is treated as a heading candidate, so this setting should not be applied blindly to dialect-specific constructs outside fences.

Wrap Paragraphs (80 chars) wraps each eligible non-empty physical line by spaces. It does not combine adjacent lines into semantic paragraphs. Headings, lists, quotes, tables, and fenced code follow their own branches, while ordinary lines are wrapped independently. Long words and inline constructs are not split internally.

A documentation editing sequence

Paste a focused section first, particularly when a file contains frontmatter, MDX components, custom directives, or embedded HTML. Leave wrapping disabled and normalize headings, bullets, and tables. Inspect the preview, then enable wrapping only if the repository enforces an 80-column prose convention.

Verify fenced examples byte for byte. Check nested lists, task boxes, hard line breaks, inline HTML, reference definitions, footnotes, and tables. Copy the result into the source through a diff, or download the generated file. Clear resets both panes when moving to unrelated content.

Render with the same Markdown implementation used by the destination. CommonMark, GitHub Flavored Markdown, MDX, Pandoc, and documentation frameworks disagree on extensions and edge cases. Run link checking, documentation builds, spelling rules, and formatting checks supplied by the repository. A source preview on this page is not an HTML rendering preview.

For large documentation sets, automate a pinned Markdown formatter in CI. Shared configuration determines line width, bullet policy, table behavior, frontmatter handling, and excluded generated files. Manual browser formatting is better for isolated cleanup and understanding a proposed style.

Tables deserve special inspection

The table aligner expects leading-pipe rows. A table written without an initial | will be handled as ordinary text. Consecutive pipe-starting lines are grouped, even if they do not form a valid header, divider, and body sequence. The tool formats appearance but does not validate the table grammar.

Column count is the maximum found in the group. Short rows receive empty cells; this can make malformed source look orderly without fixing its intended data. Alignment is inferred only from a divider row whose every cell matches optional colon, one or more dashes, and optional colon. Inline code containing a pipe may be split unless the pipe is escaped, because the implementation does not parse backtick spans within cells.

Wide tables can become much wider after padding. That is expected for visual source alignment but may conflict with line-length rules. Disable table alignment when compact source is preferable or use one item per section instead of a table for long prose.

What remains untouched, and what does not

Inside a detected fenced code block, original lines and indentation survive. A fence is recognized when the trimmed line starts with three backticks or three tildes; the same three-character kind closes it. Longer fence subtleties and nested fence rules are simplified, so examples containing fence markers need review.

Blank lines are preserved in ordinary processing, unlike several line formatters. The tool does not automatically insert blank lines around headings or lists. Existing paragraph structure therefore largely remains.

Block quotes are normalized to one space after >, but nested quote markers on the same line are treated as quote content rather than recursively normalized. Ordered list spacing is cleaned while original numbers remain. Setext headings, thematic breaks, link definitions, images, emphasis, and inline code are not deliberately rewritten.

When wrapping is enabled, Markdown’s two-space hard-break convention can be lost because ordinary lines are trimmed before wrapping. Inline links with spaces in titles, HTML attributes, and long code spans can also be awkwardly distributed. Keep wrapping off for unfamiliar content.

Frontmatter is not specially recognized by the component. A YAML block may pass mostly unchanged when wrapping is off, but lines beginning with Markdown-significant characters can take other paths. MDX JSX and expression braces likewise require an MDX-aware parser.

Troubleshoot by content type

A table gained empty cells. Rows had inconsistent column counts. Correct the source data instead of relying on padding.

A pipe inside code became a new column. Escape it as \| where the target dialect supports that, or disable alignment and use a parser-aware table formatter.

A paragraph’s intentional line break vanished. Wrapping trims physical lines and does not preserve trailing two-space breaks. Restore the source and disable wrapping.

A list marker did not change. Recognized bullets require -, *, or + followed by whitespace. A compact form such as *item is not treated as a list item.

Code changed despite fencing. Check that opening and closing fences use detectable backtick or tilde markers. For nested or longer fences, avoid the transformation and use project tooling.

Markdown Formatter FAQ

Does it render Markdown to HTML?

No. It produces formatted Markdown source. Use the destination renderer to verify visual output and generated links.

Will it preserve fenced code blocks?

Standard triple-backtick and triple-tilde blocks are passed through line by line. Complex nesting and unusual fences still require inspection.

Can it align tables with escaped pipes?

Yes, \| is protected during basic cell splitting. Pipes inside inline code are not automatically recognized as literal.

Does 80-character wrapping understand paragraphs?

It wraps eligible lines independently at spaces. It is not a prose reflow engine and does not merge a paragraph’s existing lines.

Is the selected bullet semantically important?

Usually the three markers represent equivalent unordered lists, but surrounding spacing and dialect features can matter. Consistency mainly improves source diffs and editing.

Is downloaded output ready to publish?

Run the documentation build, Markdown lint rules, link checker, and visual review first, especially for MDX, frontmatter, custom containers, and hard line breaks.

Keep formatting-only changes reviewable

When cleaning an established guide, separate prose revisions from source-format changes. A dedicated formatting commit lets reviewers verify tables, lists, and wrapping without hunting for altered meaning. It also makes blame history easier to follow. Avoid formatting generated API references or vendored documentation at all; update their generator or upstream source. For hand-written pages, preview narrow and wide layouts because a tidy source table can still overflow the rendered content area, and an 80-column paragraph can render differently once links, typography, and responsive containers are applied.