Markdown Linter: Catch Broken Markdown in Your Browser

Using the Markdown Linter in practice

The linter is most useful as a final pass before you commit or publish. Most people write Markdown fast and catch syntax errors only when the rendered page looks wrong, by which point someone has already seen it. Pasting a draft here for thirty seconds catches the half-dozen issues you accidentally introduced and would have to fix later anyway.

Concrete example one: a README. You wrote headings while you were thinking, and somewhere along the way you went from H2 to H4 without an H3 in between. GitHub renders it fine. Screen readers and the accessibility report in your CI pipeline flag it. The linter shows the exact line, you demote or promote as needed, done. Same story with images: it is easy to paste a screenshot into a Markdown file and end up with ![](screenshot.png). The linter flags every empty alt attribute so you can add descriptions before merging.

Concrete example two: a blog post with tables. Markdown tables are a common cause of silently broken renders. If one row has three columns and another has four, some renderers drop the extra cell, some add a phantom column, some just fail to render the table at all. The linter counts pipes in each row and tells you which line is off. A 30-second fix instead of a broken production page.

Concrete example three: exports from Notion, Obsidian, or Google Docs. These often produce Markdown with mixed list markers (dashes and asterisks in the same document), bare URLs pasted as-is, and trailing whitespace on every line. The linter surfaces all three in one pass so you can clean up a whole document in a single editing session. For a deeper dive on where Markdown fits in a modern writing stack, see 10 things you can do with Markdown. If you need to convert an HTML export into clean Markdown before linting, the HTML to Markdown converter gets you most of the way there in one step.