Markdown Formatter & Linter

What the formatter changes — and what it never touches

The formatter changes how your Markdown is written, not what it says. It uses the same Markdown printer as Prettier, so the result matches what a team gets from prettier --write in a project: - for bullet lists, consistent _italic_ and **bold**, numbered lists renumbered, one blank line between blocks, trailing spaces removed, and table columns padded so the pipes line up.

Your words, links, code and front matter are not edited. Text inside fenced code blocks is kept character for character — the formatter does not reindent or reflow code — and YAML front matter at the top of the file is left alone. Underlined headings (Title over =====) become # Title unless you turn that option off, because # headings are what most editors, linters and table-of-contents tools expect.

Formatting the same text twice gives the same result, so it is safe to run on a file again after you edit it, and a formatted file produces clean diffs in Git: only the lines you actually changed show up next time.

Options explained

Keep my line breaks

Leaves where you break lines alone. This is the safest choice for README files and notes, and for any text where a line break is meaningful.

Wrap long lines

Re-wraps paragraphs at 80, 100 or 120 characters. Rendered output is the same, because Markdown treats a single line break inside a paragraph as a space; only the source changes. Useful when a project requires a maximum line length.

One line per paragraph

Joins each paragraph into a single line, so an editor’s soft wrap controls the width and a one-word edit changes one line in a diff. Headings, lists and tables are not joined.

Nested list indent

2 spaces suits most projects. Choose 4 spaces if your tooling requires it: some older renderers need nested items indented past the parent’s marker.

Underlined headings → # headings

Converts Title / ===== and Section / ----- to # and ##. Turn it off to keep the original style.

What the linter checks

Formatting can tidy layout, but it cannot guess what you meant, so some problems are only flagged — each with its line number. The panel under the editor says which problems the formatted output already fixed and which need your decision.

Skipped heading level

A ### right after a # leaves a gap in the outline. Screen readers, tables of contents and search engines read headings as a hierarchy, so go one level at a time.

More than one H1

A page or README normally has one # title. A second one usually means a section that should be ##.

Duplicate heading

Two headings with the same text at the same level get anchors like #setup and #setup-1, which makes links to them easy to break.

No space after #

#Heading is plain text in most renderers, including GitHub. Add a space to make it a heading.

Empty link, image without alt text

[text]() goes nowhere. ![](image.png) gives screen readers and search engines nothing to describe; put a short description in the brackets.

Spaces inside emphasis

** bold ** is not bold: the markers must touch the text.

Uneven table rows

A row with more or fewer cells than the header is padded or cut by renderers, hiding data.

Unclosed code fence

A fence that never closes turns the rest of the document into code.

Bare URL

Many renderers link a plain address, some do not. <https://example.com> works in all of them.

Formatting automatically in a project

This page is for one-off clean-ups: pasting in a README, a note exported from another tool, or text from an AI assistant. For a project with several contributors, run the same formatting on every commit instead: install Prettier (npm install --save-dev prettier) and run npx prettier --write "**/*.md", or add it to a pre-commit hook or your CI. The result matches what this page produces. For rules about content — heading order, link style — markdownlint offers the most complete rule set to run alongside it.