Running a grammar checker over Markdown usually ends in chaos: code blocks flagged as prose, YAML frontmatter rewritten, links mangled. If your docs live in .md files — READMEs, Wikis, API docs, CHANGELOGs — you need a checker that parses the format instead of fighting it.
What Goes Wrong When Grammar Checkers Meet Markdown
| Element | Typical checker behavior |
|---|---|
`code blocks` |
Treated as prose; variables like getUserById() flagged as typos |
| YAML frontmatter | Key-value pairs "corrected" into sentences |
Inline code `npm install`
|
Backticks stripped or "fixed" to normal text |
| Links | Anchor text rewritten, URLs altered |
| Tables | Pipe syntax mangled |
The root problem: most checkers run their engine over the entire file as if it were plain prose. They have no parser for Markdown structure and no awareness that fenced blocks contain code.
What a Code-Aware Markdown Checker Should Do
-
Fenced block detection: everything inside
`is skipped entirely, not spell-checked - Inline code protection: text between single backticks is never edited
-
Technical term whitelist:
localhost,NaN,OAuth2,CLIare recognized, not flagged - Structure preservation: tables, lists, and frontmatter come out byte-identical
- Diff output: you see exactly what changed, so nothing ships by accident
Testing 4 Popular Checkers on a Real README
We ran the same 900-word README — with three code blocks, two tables, YAML frontmatter, and inline code — through four tools:
| Tool | Code blocks intact | Inline code intact | False positives |
|---|---|---|---|
| Lint | ✅ Yes | ✅ Yes | 0 |
| Grammarly (web) | ⚠️ Pasted as plain text, structure lost | ❌ Stripped | 14 |
| LanguageTool | ⚠️ Partial with plugins | ⚠️ Sometimes | 6 |
| Hemingway Editor | ❌ No code awareness | ❌ No | 9 |
Lint was the only tool that left the Markdown file structurally untouched while still catching real grammar mistakes in the prose sections. Its code-aware layer detects fenced blocks, inline code, and common technical tokens before the grammar engine runs.
A Practical Workflow for Proofreading Markdown
- Proofread the prose, not the file. If your tool lacks code awareness, strip code blocks first — but that is tedious for every commit.
- Prefer tools with a diff view. Accepting changes blindly is how broken documentation gets merged.
- Check readability separately. A readability analyzer helps you keep sentences short without touching code.
- Automate on your own terms. An API-based checker (like Lint's) can be wired into CI so only the prose changes trigger checks.
Bottom Line
If your documentation lives in Markdown — and as a developer, it does — you need a checker that parses the format instead of fighting it. Lint checks Markdown prose for grammar while leaving code blocks, inline code, and structure untouched.
Free tier: 3 checks a day, no signup. Or bring your own DeepSeek/OpenAI-compatible API key with BYOK for unlimited use at $0.
Top comments (0)