Free tool · works now

Markdown Lint Explainer

Understand syntax problems, broken links, and heading hierarchy skips with plain-English CommonMark explanations.

Runs 100% in your browser. Audit Markdown files for syntax errors, heading hierarchy jumps, and broken links with plain-language explanations citing the CommonMark specification.

7Issues detected
3Syntax errors
2Structural warnings
2Style notices
5Auto-fixable
13Clean lines
Markdown document editorPaste text to lint

Paste articles, notes, or README files. Code blocks are quarantined from false alarms.

Explanations & suggested fixes7 findings to review
ERRORMD018(no-missing-space-atx)
Line 1:2

ATX headings require a space between the "#" symbols and the heading text. Without a space, standard Markdown parsers treat this as literal text or a tag.

#Technical Architecture Overview
📖 CommonMark 0.31 §4.2 (ATX headings require space)✨ Auto-Fixable
ERRORMD011(reversed-link-syntax)
Line 8:33

Reversed link syntax detected: "(text)[url]" was written instead of "[text](url)". This renders as raw text rather than a hyperlink.

Here is a reversed link syntax: (Project Documentation)[https://example.com/docs].
📖 CommonMark 0.31 §6.3 (Links syntax: [text](href))✨ Auto-Fixable
ERRORMD042(no-empty-links)
Line 9:36

Link "[Read more]()" has an empty destination URL (). This renders a dead link.

Here is an empty link destination: [Read more]().
📖 CommonMark 0.31 §6.3 (Inline links)
WARNINGMD037(no-space-in-emphasis)
Line 11:20

Spaces inside emphasis markers ("* bad italics with spaces *") prevent CommonMark parsers from activating italics or bold formatting.

This paragraph has * bad italics with spaces * and ** bold formatting **.
📖 CommonMark 0.31 §6.2 (Emphasis delimiter flanking rules)✨ Auto-Fixable
STYLEMD040(fenced-code-language)
Line 13:1

Code fence lacks a language identifier (e.g. ```typescript or ```markdown). Syntax highlighters and linters cannot format the block.

```
📖 CommonMark 0.31 §4.5 (Info strings)
WARNINGMD031(blanks-around-fences)
Line 18:1

Fenced code blocks must be followed by a blank line to cleanly separate them from subsequent prose.

```
📖 CommonMark 0.31 §4.5 (Fenced code blocks)✨ Auto-Fixable
STYLEMD009(no-trailing-spaces)
Line 19:41

Line has 4 trailing whitespace character(s). Accidental whitespace causes git diff noise. Note: Exactly two trailing spaces are permitted for hard line breaks.

Trailing spaces at the end of this line.
📖 CommonMark 0.31 §6.7 (Hard line breaks)✨ Auto-Fixable

Plain-language breakdown citing CommonMark specifications. Click "Apply safe auto-fixes" to resolve eligible issues.

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:

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

  1. Paste your Markdown document: Enter your note, blog draft, or README text into the editor panel above.
  2. Review the severity matrix: Check the stats ribbon for errors, warnings, and style hints.
  3. Inspect specific findings: Read the plain-English explanations and spec citations in the right panel.
  4. Apply safe auto-fixes: Click Apply safe auto-fixes to correct spacing, bare URLs, and emphasis syntax automatically.
  5. Copy clean Markdown: Click Copy fixed Markdown to paste the sanitized text directly into your project.

Questions

How does the Markdown Lint Explainer distinguish broken syntax from style preferences?

The engine categorizes findings into three distinct severity levels: Errors represent true syntax breaks (such as missing spaces after ATX hash symbols, reversed [text](url) link brackets, or empty destinations) that cause parsers to fail. Warnings represent structural flaws (such as skipped heading levels or duplicate anchor names) that impair screen reader navigation. Style hints represent cosmetic conventions (such as missing language tags on code fences or trailing spaces).

Why are spaces inside emphasis delimiters (* italic *) considered invalid in CommonMark?

CommonMark 0.31 §6.2 enforces strict "delimiter flanking" rules. For an asterisk to open emphasis, it must be followed by a non-whitespace character. A space immediately after the opening asterisk (e.g. * word *) causes standard Markdown parsers to treat the asterisk as literal punctuation rather than activating italics.

Why do skipped heading levels (H1 directly to H3) trigger a warning?

Skipping heading levels violates W3C WCAG 2.2 accessibility guidelines (Success Criterion 1.3.1). Screen reader users navigate long documents by jumping between heading levels; jumping from H1 directly to H3 confuses assistive technology by implying missing sections.

Are code blocks and quoted examples protected from false positive warnings?

Yes. Any text inside fenced code blocks (``` or ~~~) is strictly quarantined. Markdown characters inside code examples (such as #comments or URL strings) will never trigger false-positive lint issues.

How does the safe auto-fix feature work?

When you click "Apply safe auto-fixes", the engine applies deterministic transformations: it adds missing spaces to ATX headings (# ), wraps bare URLs in angle brackets (<url>), removes spaces inside emphasis (*italic*), and strips accidental trailing whitespace while carefully preserving 2-space intentional line breaks.

Does this tool transmit my Markdown notes or articles over the network?

No. The entire lint parser, CommonMark rule checks, before-and-after preview generator, and CSV export execute entirely inside your local browser tab memory. Zero network requests or telemetry events are transmitted.

Write clean, portable Markdown with confidence

Private on-device text intelligence and native Markdown editing in Oyma. Keep your technical writing accessible and error-free.

tools markdown lint explainer downloadDownload for Mac

No account needed. Intel Mac build