How to lint markdown for style and syntax issues
- Step 1Paste or upload the Markdown — Switch to Paste text and drop your Markdown in, or use Upload file to pick a single
.md,.mdx,.markdown, or.txtfile. The character counter under the box turns red if you exceed your plan's limit. - Step 2Run the linter — Click Run MD Lint. The scan happens locally in your browser — there is no options panel to configure because the 12-rule set is fixed.
- Step 3Read the report header — The top of the report shows
# Lint Reportand a line likeFound 7 issues:. If your doc is clean it instead says✓ No issues found. Your Markdown is clean. - Step 4Work down the line-numbered list — Each entry reads
**Line N** ·MDxxx— message. Open that line in your editor and apply the change. Entries for MD009/MD010/MD018/MD019 include a→ Suggested fix:you can copy verbatim. - Step 5Apply fixes yourself — There is no auto-apply button — edit your source in your own editor. For bulk whitespace and blank-line normalization, run the result through md-prettifier instead.
- Step 6Copy or download, then re-run — Use Copy to grab the report or Download to save it as
<name>-lint.txt. After editing, paste the new version and run again until the count reaches zero.
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
Real before/after pairs. The left side is the Markdown you paste in; the right side is the exact text the linter prints for it. Line numbers are 1-based and match the report.
Heading with no space after the hash (MD018)
The most common style hit: an ATX heading glued to its marker. MD018 fires and carries a suggested fix.
Input: ##Setup Report: # Lint Report Found 1 issue: **Line 1** · `MD018` — No space after ATX heading marker → Suggested fix: `## Setup`
Trailing whitespace left by an editor (MD009)
Two trailing spaces — sometimes an intentional hard line break, but flagged either way so you can decide. The fix trims the line.
Input (note the two spaces after 'done'): The migration is done.·· Report: **Line 1** · `MD009` — Trailing whitespace → Suggested fix: `The migration is done.`
A reversed link that renders as literal text (MD011)
Writing the parts backwards is invisible until it renders as plain text. MD011 catches it; no auto-fix, so swap the brackets yourself.
Input: See the (docs)[https://example.com] for details. Report: **Line 1** · `MD011` — Reversed link syntax — use [text](url), not (text)[url]
A second H1 after a copy-merge (MD025)
Two top-level headings confuse outline generators and accessibility tools. MD025 flags the second one; demote it to H2 by hand.
Input: # Release Notes Text. # Changelog Report: **Line 5** · `MD025` — Multiple top-level headings in document **Line 5** · `MD022` — Headings should be surrounded by blank lines
A clean document
When nothing trips a rule, the report is a single reassuring line — useful as a pre-publish gate.
Input: # Title Well-formed body text. Report: # Lint Report ✓ No issues found. Your Markdown is clean.
Edge cases and what actually happens
MD001 flags every H2–H6, not just real level skips
HeuristicMD001 is implemented as a simple pattern that matches any line beginning with ## through ######. It does not compare a heading to the one before it, so it reports on every sub-heading in the document rather than only on a true level jump (like H1 → H3). Treat MD001 as a prompt to eyeball your heading ladder, not as a precise skip detector.
Two trailing spaces are an intentional line break
By designMD009 flags any trailing whitespace, including the two-space hard line break some authors use. If you rely on that style, MD009 will report it and the suggested fix would remove it — skip that fix on the lines where the break is deliberate.
Rules scan inside fenced code blocks too
ExpectedThe linter works line by line and is not fence-aware. A tab or trailing space inside a triple-backtick code block still triggers MD010 or MD009, and a # comment line inside a shell block can look like a heading. This keeps whitespace honest but means some hits inside code are intentional — review them in context.
Setext headings are not seen as H1
Not detectedMD025 (single H1) only matches ATX # headings. A heading written in setext style (a line of text underlined with ===) is not counted, so a setext H1 plus an ATX # will not be flagged as a duplicate. Use ATX # headings if you want this rule to apply.
Empty input
PreservedPasting nothing leaves the Run button disabled (it requires at least one character or one uploaded file). An effectively empty file produces the clean-bill ✓ No issues found report, since no line trips a rule.
Allowlisted inline HTML passes MD033
SupportedMD033 ignores a fixed allowlist of common tags — img, br, hr, a, span, div, code, pre, sup, sub. So <br> or <sup>2</sup> will not be flagged, while <table> or <details> will. The allowlist is fixed and cannot be edited.
Over the character limit
400 rejectedFree tier caps input at 500,000 characters (1 MB files). Paste more and the counter turns red and the Run button is disabled until you trim or upgrade. Pro raises this to 5,000,000 characters / 10 MB.
The report is markdown-formatted text
ExpectedThe report itself uses Markdown (# Lint Report, **Line N**, backticks). It is delivered as text/plain and shown verbatim in a scrollable panel; it is not rendered. Copy it into an issue tracker and it will format nicely there.
No corrected copy is produced
By designmd-lint reports problems; it does not return an edited document. For automatic whitespace/blank-line cleanup use md-prettifier; for broken list markers use md-list-fixer; for misaligned tables use md-table-repair.
Frequently asked questions
Which rules does it check?
Twelve, in the browser: MD001 (heading levels), MD009 (trailing whitespace), MD010 (hard tabs), MD011 (reversed links), MD012 (consecutive blank lines), MD018 (no space after #), MD019 (multiple spaces after #), MD022 (blank lines around headings), MD025 (single top-level H1), MD031 (blank lines around fenced code), MD033 (inline HTML), and MD047 (file ends with a newline).
Can I turn rules on or off?
No. The rule set is fixed and there is no options panel for this tool — every run checks all 12 rules. If a particular rule does not fit your house style, simply ignore those entries in the report.
Does it auto-fix my document?
No. It produces a text report, not a corrected file, and there is no "Apply all fixes" button. Four rules (MD009, MD010, MD018, MD019) include a ready-to-paste suggested-fix line; you apply edits in your own editor.
Does it check bare URLs (MD034) or trailing heading punctuation (MD026)?
No. Those markdownlint rules are not implemented here. The 12 rules listed above are the complete set; if you need bare-URL detection, that is outside this tool's scope.
Will it find every rendering problem?
It finds the common, mechanical ones in its 12-rule set. Renderer-specific quirks (a particular GFM extension, a CommonMark vs. GFM difference) still need a check in your actual target renderer.
Is my document uploaded anywhere?
No. In the browser the entire scan runs locally — your Markdown never leaves the page. That is what makes it safe for confidential or unpublished drafts.
What file types can I lint?
Paste any text, or upload a single .md, .mdx, .markdown, or .txt file. The tool processes one file per run.
How big a file can I lint?
Free tier allows 1 MB / 500,000 characters per run. Pro raises it to 10 MB / 5,000,000 characters, Pro + Media to 50 MB / 20,000,000, and Developer to 500 MB / unlimited characters.
Why does MD001 flag every sub-heading?
Its implementation matches any H2–H6 line rather than comparing adjacent heading levels, so it lists each one. Read it as a nudge to scan your heading hierarchy rather than a strict skipped-level detector.
Does it skip code blocks?
No — the scan is line-based and not fence-aware. Tabs, trailing spaces, and #-prefixed lines inside fenced code can still trigger MD010, MD009, or heading rules. Review hits that fall inside code in context.
Can I run this in CI?
Yes. The same linter is exposed through the public API and MCP, so an automated check reports the same 12 rules as the browser. Wire that call into your pipeline to lint on every push.
What should I run after fixing the report?
For automated tidy-up, send the document through md-prettifier. For specific structural issues, use md-list-fixer, md-table-repair, or md-heading-shifter, then re-lint until the count is zero.
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.