How to detect common markdown syntax errors
- Step 1Drop in the document — Use Paste text for a quick check or Upload file for a single
.md/.mdx/.markdown/.txt. Watch the character counter against your plan limit. - Step 2Run the scan — Click Run MD Lint. The 12-rule scan runs locally — there are no settings, so the same errors are caught every time.
- Step 3Read the error list — The report lists each hit as
**Line N** ·MDxxx— message. Reversed links (MD011), glued headings (MD018), and un-surrounded fences (MD031) are the ones most likely to be breaking your render. - Step 4Fix the rendering-breakers first — Correct MD011, MD018, MD025, and MD031 first — these are the rules whose violations actually change how the page renders.
- Step 5Apply suggested fixes where given — MD009, MD010, MD018, and MD019 include
→ Suggested fix:lines. Paste those directly; the other rules you fix by hand. - Step 6Re-run, then preview in your renderer — Re-paste and run until the count is zero, then do a final visual check in your actual target renderer for issues outside the 12-rule set.
Every rule the linter checks (12 total)
The browser linter scans your Markdown line by line and applies these 12 markdownlint-style rules. Only four rules carry an auto-generated suggested-fix string in the report; the rest are reported for you to fix by hand. There are no rule toggles — the set is fixed.
| Rule | Triggers when | Suggested fix in report? |
|---|---|---|
MD001 | A line is an H2–H6 heading (heuristic for heading-increment problems) | No — manual |
MD009 | A line ends with one or more trailing spaces or tabs | Yes — line trimmed |
MD010 | A line contains a hard tab character | Yes — each tab → two spaces |
MD011 | A reversed link (text)[url] appears instead of [text](url) | No — manual |
MD012 | A blank line follows another blank line (consecutive blanks) | No — manual |
MD018 | An ATX heading has no space after the # markers, e.g. ##Heading | Yes — space inserted |
MD019 | An ATX heading has more than one space after the #, e.g. ## Heading | Yes — collapsed to one |
MD022 | A heading is not preceded by a blank line | No — manual |
MD025 | A second (or later) # top-level H1 appears in the document | No — manual |
MD031 | A fenced code block opener is not preceded by a blank line | No — manual |
MD033 | Inline HTML outside the allowlist (img, br, hr, a, span, div, code, pre, sup, sub) | No — manual |
MD047 | The file's last line is not empty (no final newline) | No — manual |
What the report contains vs. what it does not
The result is a plain-text report, not an edited copy of your document. It is shown in a scrollable panel with Copy and Download buttons; downloads save as <name>-lint.txt. The tool never rewrites your source.
| You get | You do not get |
|---|---|
A # Lint Report header and a total issue count | A corrected/auto-fixed copy of your Markdown |
One **Line N** · MDxxx — message entry per violation | An "Apply all fixes" button (no such control exists) |
A → Suggested fix: line for MD009/MD010/MD018/MD019 only | Rule selection, severity levels, or config files |
| A clean-bill message when zero issues are found | Multi-file / folder batch linting in one run |
Input limits by plan (markdown family)
md-lint runs entirely in your browser and processes one file per run. The character limit is enforced live in the paste box; the byte limit applies to uploaded files. Both are distinct numbers — a small file with lots of characters can still hit the char limit first.
| Plan | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 1 (this tool takes a single file) |
| Pro + Media | 50 MB | 20,000,000 | 1 |
| Developer | 500 MB | Unlimited | 1 |
Cookbook
Each pair shows a real rendering-breaker on the left and the exact line-numbered report on the right. Fix the source, not the report.
Reversed link renders as plain text (MD011)
The classic silent break: parentheses and brackets swapped. The page shows the literal characters instead of a link. MD011 catches it.
Input: Download the (installer)[https://example.com/dl]. Report: **Line 1** · `MD011` — Reversed link syntax — use [text](url), not (text)[url]
Code fence absorbed into the paragraph (MD031)
No blank line before the opening fence, so some parsers fold it into the preceding text and the code never renders as a block.
Input: Run this command: ``` npm install ``` Report: **Line 2** · `MD031` — Fenced code blocks should be surrounded by blank lines
Heading that never becomes a heading (MD018)
No space after the hashes, so it renders as literal '##Overview' text. The suggested fix inserts the space.
Input: ##Overview Report: **Line 1** · `MD018` — No space after ATX heading marker → Suggested fix: `## Overview`
Duplicate H1 breaks the auto-TOC (MD025)
Two top-level headings confuse table-of-contents generators and document outlines. MD025 flags the second; demote it.
Input: # API Reference Text. # Appendix Report: **Line 5** · `MD025` — Multiple top-level headings in document
No errors — safe to publish
When the mechanical checks all pass, the report is a single clean-bill line.
Input: # Guide Properly formed content. Report: # Lint Report ✓ No issues found. Your Markdown is clean.
Edge cases and what actually happens
Renderer-specific bugs are out of scope
Not detectedThe 12 rules cover mechanical Markdown syntax, not differences between how GFM, CommonMark, and other parsers handle edge constructs. After clearing the report, preview in your actual renderer for anything parser-specific.
MD001 over-reports heading levels
HeuristicMD001 flags every H2–H6 line rather than only true level skips. It will not reliably tell you that you jumped H1 → H3; it just marks sub-headings. Verify the hierarchy yourself.
MD031 only checks the line above the opening fence
PartialThe fenced-code rule looks at whether the line before the opening ``` is blank. It does not separately verify the blank line after the closing fence, so a fence with text directly after it can still slip through this check.
Errors inside code blocks are still reported
ExpectedBecause the scan is not fence-aware, a tab, trailing space, or #-led line inside a code block triggers the matching rule. Some of those are legitimate code, so judge hits inside fences in context.
Reversed link with no fix line
ExpectedMD011 has no auto-suggested fix — the report names the problem but you must swap the brackets to [text](url) yourself. Only MD009, MD010, MD018, and MD019 carry suggested fixes.
Setext H1 not counted as a duplicate
Not detectedMD025 only sees ATX # headings. A setext-style H1 (underlined with ===) plus an ATX # will not be flagged as two top-level headings. Use ATX # headings for reliable detection.
Empty or whitespace-only document
PreservedAn empty document yields the clean-bill report. The Run button stays disabled until there is at least one character pasted or a file selected.
Input exceeds the size limit
400 rejectedOver 500,000 characters (Free) the counter turns red and Run is blocked. Trim the document or upgrade to Pro for 5,000,000 characters / 10 MB.
No corrected document is returned
By designThe tool reports errors; it does not rewrite the file. For structural auto-repair, use the targeted siblings: md-table-repair, md-list-fixer, or md-prettifier.
Frequently asked questions
What errors does it find?
Reversed links (MD011), headings glued to or padded after their hashes (MD018/MD019), code fences and headings without surrounding blank lines (MD031/MD022), duplicate top-level H1s (MD025), hard tabs (MD010), trailing whitespace (MD009), consecutive blank lines (MD012), non-allowlisted inline HTML (MD033), the heading-level heuristic (MD001), and a missing final newline (MD047).
Will it find every rendering issue?
It finds the common mechanical ones in its 12-rule set. It does not model parser-specific behavior, so after fixing the report you should still preview in your actual target renderer.
Does it detect unclosed code fences or unbalanced emphasis?
No. There is no rule for unmatched `` fences or unbalanced **/*` markers. For emphasis-marker cleanup see md-bold-italic-cleaner; for code-block language tagging see md-code-block-tagger.
Does it check for broken or dead links?
No. MD011 only catches the reversed (text)[url] syntax; it does not verify that a URL resolves. To check whether links actually work, use md-link-validator.
Why is there no fix for some errors?
Only four rules (MD009, MD010, MD018, MD019) have a deterministic single-line fix. Errors like a duplicate H1 or a reversed link need a human decision, so they are reported without a suggested fix.
Is my document sent to a server?
No. The browser runs the scan locally, which is why it is safe for internal and pre-release docs.
What can I check?
Paste text, or upload a single .md, .mdx, .markdown, or .txt file. One file per run.
How large a file can it handle?
Free: 1 MB / 500,000 characters. Pro: 10 MB / 5,000,000. Pro + Media: 50 MB / 20,000,000. Developer: 500 MB / unlimited characters.
Does it auto-fix the broken syntax?
No — it reports a list of issues. You edit the source yourself; the four fixable rules give you a paste-ready corrected line in the report.
Does it scan inside code blocks?
Yes, the scan is line-based and not fence-aware, so tabs and #-prefixed lines inside fenced code can be flagged. Review those hits in context since they may be intentional code.
Can I run this automatically before publishing?
Yes. The same linter is available via the public API and MCP, so you can call it from a publish script or CI step and gate on a zero-issue report.
What do I run after the report is clean?
Preview in your target renderer, and if you need structural cleanup run md-prettifier or md-table-repair, then re-scan to confirm.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.