How to audit markdown documentation quality
- Step 1Pick a doc to audit — Audit the most-read or most-edited pages first. Choose Paste text, or Upload file for a single
.md/.mdx/.markdown/.txt— one document per run. - Step 2Run the audit — Click Run MD Lint. The 12-rule scan runs locally with no configuration, so each audit measures the same things.
- Step 3Record the issue count — Note the
Found N issues:total. Tracking that number across audits is a simple, honest hygiene metric for a page or a set of pages. - Step 4Prioritize the findings — Functional first — MD025 (duplicate H1), MD011 (reversed link), MD031/MD022 (block spacing). Cosmetic next — MD009 (trailing space), MD012 (extra blanks).
- Step 5Schedule and assign fixes — Turn the report into tasks. Quick wins (MD009/MD010/MD018/MD019) carry paste-ready fixes; the rest become editorial tickets keyed to the rule IDs.
- Step 6Re-audit on a cadence — Re-run after fixes to confirm, and audit important pages on a schedule (quarterly, or monthly for fast-moving docs) to catch new drift early.
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
Audit-style before/after pairs drawn from the kinds of drift long-lived docs accumulate. Left is the doc as found; right is the exact audit report.
Duplicate H1 from a doc merge (MD025)
Two pages combined into one, each keeping its # H1. The audit flags the second so you can fix the outline.
Input: # Operations Runbook Steps. # Incident Playbook Report: **Line 5** · `MD025` — Multiple top-level headings in document
Accumulated trailing whitespace (MD009)
Years of edits leave trailing spaces scattered through a page. The audit lists each line; the suggested fix trims it.
Input (trailing space after 'restart'): Then restart the service.· Report: **Line 1** · `MD009` — Trailing whitespace → Suggested fix: `Then restart the service.`
Heading spacing drift (MD022)
A section heading that lost its blank line above during an edit. Small, but it adds up across a long runbook.
Input: Previous step finishes. ## Rollback Procedure Report: **Line 2** · `MD022` — Headings should be surrounded by blank lines
Stray raw HTML from an old paste (MD033)
A <details> block pasted long ago. MD033 flags non-allowlisted tags so you can decide whether to keep or convert them.
Input: <details><summary>More</summary>Extra info</details> Report: **Line 1** · `MD033` — Inline HTML detected (use Markdown equivalents when possible)
A page that passes the audit
A well-maintained page returns a clean bill — the baseline you want every audited doc to reach.
Input: # Deployment Guide Clear, well-structured, current content. Report: # Lint Report ✓ No issues found. Your Markdown is clean.
Edge cases and what actually happens
It audits mechanics, not content quality
By designThe audit measures formatting hygiene only. It cannot tell you whether a doc is accurate, complete, current, or readable. Treat a clean report as a mechanical baseline, then do an editorial content review separately.
MD001 inflates the count
HeuristicBecause MD001 flags every H2–H6 line, a heading-rich page can show a large MD001 tally that does not reflect real heading-skip problems. When trending the issue count, consider excluding MD001 for a cleaner signal.
One document per audit run
ExpectedThe tool audits a single file at a time. To audit a whole docs set, run each page in turn, or call the same linter via the public API from a script that walks the repository and aggregates counts.
Code blocks are included in the scan
ExpectedThe scan is not fence-aware, so tabs, trailing spaces, and #-led lines inside fenced code count toward the report. For a content-only audit you may want to mentally discount in-code hits.
Two-space hard line breaks counted
ExpectedMD009 flags intentional two-space line breaks the same as accidental trailing whitespace. If your docs use that style, expect those to appear in every audit.
Setext headings not audited for duplicates
Not detectedMD025 only counts ATX # H1s. Older docs using setext underline-style headings can hide a duplicate top-level heading from the audit. Normalize to ATX # for full coverage.
Large pages exceed the size cap
400 rejectedA very long manual can pass Free's 500,000-character / 1 MB limit; the counter turns red and Run is disabled. Split the page or upgrade to Pro (5,000,000 chars / 10 MB) to audit it whole.
Report is a list, not a graded score
ExpectedThere is no letter grade or percentage — the output is a line-numbered issue list plus a total count. Build your own quality metric by tracking that count over successive audits.
No edited copy is produced
By designThe audit identifies issues; it does not rewrite the page. For mechanical cleanup after the audit, run the doc through md-prettifier or fix structures with md-table-repair and md-list-fixer.
Frequently asked questions
How often should I audit?
Quarterly for important, stable docs; monthly for fast-moving content; and after any major rewrite or merge. Re-run after applying fixes to confirm the page reaches a clean report.
What exactly does the audit measure?
Twelve mechanical rules: heading spacing and surrounds (MD018, MD019, MD022, MD001), whitespace and tabs (MD009, MD010), blank-line discipline (MD012, MD031), link syntax (MD011), single H1 (MD025), inline HTML (MD033), and a final newline (MD047).
Does it assess accuracy, completeness, or readability?
No. It is a formatting-hygiene audit only. Whether the content is correct, complete, current, and clear is a separate editorial judgement the tool cannot make.
Should I fix everything in the report?
Prioritize by impact. Fix functional issues first (duplicate H1, reversed links, missing block spacing), then cosmetic ones (extra blank lines, trailing whitespace). The four fixable rules are quick wins.
Can I track doc quality over time?
Yes — track the issue count across audits as a hygiene metric. For automated trending, call the same linter via the public API or MCP in a scheduled job and log the counts per page.
Can I audit a whole documentation folder at once?
Not in one browser run — it is single-file. Audit pages one at a time, or script the public API to iterate the repository and aggregate the per-file counts.
Is my documentation uploaded?
No. The browser audit runs locally, so internal wikis, runbooks, and confidential docs never leave the machine.
Will it edit or clean the doc for me?
No. It returns a report, not a corrected file, and there is no auto-apply. MD009, MD010, MD018, and MD019 include paste-ready fixes; everything else you apply by hand.
How large a doc can it audit?
Free: 1 MB / 500,000 characters. Pro: 10 MB / 5,000,000. Pro + Media: 50 MB / 20,000,000. Developer: 500 MB / unlimited characters.
Why does the inline-HTML rule ignore some tags?
MD033 has a fixed allowlist (img, br, hr, a, span, div, code, pre, sup, sub) it does not flag. Tags outside that list are reported; the allowlist cannot be customized.
Does a clean report mean the doc is good?
It means the doc is mechanically clean — well-spaced headings, no tabs or trailing whitespace, valid link syntax, a single H1, and a final newline. Content quality still needs a human review.
What should I run to clean up after an audit?
Apply quick fixes from the report, then run md-prettifier for whitespace and blank-line normalization, and md-toc-generator if the page needs a refreshed table of contents. Re-audit 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.