Why Traditional Markdown Linters Frustrate Technical Writers
Command-line Markdown linters (such as markdownlint or remark-lint) are essential tools for large software repositories, but their output often frustrates human writers. Obscure error codes like MD001, MD018, or MD037 are displayed without clear explanation of why the rule exists, what spec it derives from, or whether it represents a catastrophic rendering failure or a mere stylistic preference.
The Markdown Lint Explainer bridges this gap. Rather than emitting an opaque failure code, it diagnoses syntax issues in real time, provides plain-language explanations citing the official CommonMark 0.31 specification and W3C WCAG guidelines, and offers safe, non-destructive before-and-after auto-fixes—all running 100% locally inside your browser tab.
Broken Syntax versus Stylistic Preference: Why Nuance Matters
In technical documentation, not all lint violations carry equal weight:
- Critical Syntax Breaks (Errors): Missing spaces after ATX hashes (
#Title), reversed hyperlink brackets ((text)[url]), and empty URLs ([link]()) are true syntax failures. Modern CommonMark parsers will fail to render these elements as headings or links, causing visible presentation bugs. - Accessibility Breaks (Warnings): Skipping heading levels (such as jumping from an
# H1directly to a### H3) breaks the logical outline of the document. Visually impaired readers relying on screen readers use heading jumps to navigate; skipping levels creates confusing dead ends. - Cosmetic Conventions (Style Hints): Missing language identifiers on code fences (
```withouttypescript) or trailing whitespace characters cause no visual harm to readers, though they contribute to git diff noise and disable syntax colorization.
Understanding CommonMark Delimiter Flanking Rules
One of the most frequent surprises for Markdown writers is why emphasis fails to render when formatted with internal spaces (e.g. * bad italics *). Under the CommonMark specification (§6.2), an emphasis delimiter must be left-flanked (followed immediately by a non-whitespace character) to open an inline span, and right-flanked (preceded immediately by a non-whitespace character) to close it.
When an author places spaces inside the asterisks, standard parsers interpret the symbols as literal asterisk punctuation marks. Our explainer highlights this rule and automatically trims the internal spaces while leaving external sentence spacing intact.
Code Fence Immunity: Preventing False Alarms
A major shortcoming of rudimentary regex-based linters is false-positive reporting on code examples. A line like # This is a Python comment inside a Python code fence should never be flagged as an ATX heading issue. Similarly, bare URLs inside code blocks or API snippets must remain untouched.
Our engine implements complete code fence quarantine: the moment a triple-backtick (```) or tilde (~~~) fence opens, all prose syntax inspections are suspended until the matching closing fence is encountered. Use this tool alongside our YAML frontmatter validator and note inventory generator to audit your documentation with institutional precision.
Step-by-Step Document Remediation Protocol
- Paste your Markdown document: Enter your note, blog draft, or README text into the editor panel above.
- Review the severity matrix: Check the stats ribbon for errors, warnings, and style hints.
- Inspect specific findings: Read the plain-English explanations and spec citations in the right panel.
- Apply safe auto-fixes: Click Apply safe auto-fixes to correct spacing, bare URLs, and emphasis syntax automatically.
- Copy clean Markdown: Click Copy fixed Markdown to paste the sanitized text directly into your project.