Skip to content
Markdown Viewer

Heading Hierarchy Auditor

Audit your Markdown headings — catch skipped levels and multi-H1

Visualize the outline of any Markdown document and surface accessibility-impacting issues: skipped heading levels, multiple top-level titles, and missing H1. Runs locally so private docs stay private.

Reorder sectionsGenerate TOC slugsGFM checklist
6 heading(s) · 1 issue(s)

Detected outline

  1. L1H1Project README
  2. L3H2Getting started
  3. L5H3Install
  4. L7H4Step one
  5. L9H2Configuration
  6. L11H5Advanced

Issues

L11

Heading jumps from h2 to h5 (skipped level).

How to use the heading auditor

  1. Paste your Markdown, or click Open .md to load a file.
  2. The detected outline on the left shows every heading with its level (H1–H6), line number, and indented title.
  3. The issues panel on the right lists each problem with the line number — click through to your editor to fix.
  4. Once warnings clear, you have a structurally valid outline for tables of contents, screen-reader navigation, and SEO.

What the auditor checks

CheckSeverityWhy it matters
Skipped heading levels (H2 → H4)WarningBreaks screen-reader navigation and TOC generators.
Multiple H1 headingsWarningConfuses search engines about the document title.
No H1 at allInfoIntentional for embeds, but flagged for awareness.

Heading hierarchy 101

Treat the outline like a book: one title (H1), several chapters (H2), each chapter may have sections (H3), each section may have subsections (H4), and so on. Each step is exactly one level deeper than the previous one.

# Document title          ← H1 (one per document)

## A major section        ← H2

### A subsection          ← H3

#### A sub-subsection     ← H4

Going directly from H2 to H4 is the most common bug. It usually happens because:

  • A copy-paste from a longer document brought a deeper heading with it.
  • Someone "promoted" a section by changing an H3 to H2 but missed the H4 children.
  • AI-assisted writing introduced an inconsistent jump.

Real-world impact of skipped levels

  • Screen readers (NVDA, JAWS, VoiceOver) announce headings and let users jump between them. A skipped level either disappears from the navigation list or appears with no parent — disorienting for users who rely on it.
  • Search engines parse heading structure to understand topic relationships. A clean hierarchy improves the chance Google picks the right snippet for a long-tail query.
  • TOC generators (Docusaurus, MkDocs, Nextra) usually render the first two or three levels in a sidebar. A skipped level either drops content or renders it at the wrong depth.

Companion tools

Privacy & data

The audit is a small, deterministic scan that runs entirely in your browser. We don't upload, log, or store the Markdown you paste.

Frequently asked questions

Why do heading levels matter?
Heading hierarchy is the spine of accessibility, SEO, and document navigation. Screen readers use heading levels to let users jump between sections. Search engines weight headings to understand topic structure. Static-site TOC builders rely on consistent levels. Skipping from H2 to H4 silently breaks all three.
What does the auditor flag?
Three patterns: (1) skipped levels — a jump like H2 → H4 without a corresponding H3 in between; (2) multiple H1 headings — most platforms expect exactly one document title; (3) missing H1 — flagged as informational, since some platforms (Notion-style notes, embedded fragments) intentionally start at H2.
Is a single H1 strictly required?
It is recommended for standalone web pages, READMEs, blog posts, and most documentation. HTML5 technically allows multiple H1s inside `<section>` elements, but search engines and screen readers behave most predictably with one H1 per page. The auditor flags two or more H1s as a warning.
What about deeply nested headings (H5, H6)?
They're allowed and not flagged by themselves. If your document genuinely needs H5 or H6, that usually signals a separate concern: the document might be too long for one page. Consider splitting it with the [Merge & Split](/tools/markdown-merge-split) tool, or restructure with [Outline Reorder](/tools/markdown-outline-reorder).
Does this account for setext (===, ---) headings?
The auditor reads ATX headings (the `#` style). Setext-style underline headings are uncommon in modern Markdown — if you maintain a file with them, run a formatter pass first to convert to ATX, then audit.
Is my document uploaded?
No. The audit runs as a tiny scan inside your browser tab. We never upload, log, or store the Markdown you paste.