All tools

Markdown Heading Hierarchy Validator

Code

Validate a Markdown document's heading structure: flag skipped levels, multiple H1s, empty headings, duplicate headings, and a document that doesn't start at H1

Paste a Markdown document and get back every ATX heading it contains plus a flat list of structural issues: a level that jumps deeper by more than one step (like H1 straight to H3), more than one H1 in the same document, a heading with no text, two headings at the same level with the same text, or a document whose first heading isn't H1. These are the same conventions most Markdown style guides and linters enforce, since a broken hierarchy quietly confuses screen readers and auto-generated tables of contents even though the page still renders fine. It only recognizes ATX-style headings written with leading hash characters, not the older Setext style underlined with equals or dashes, and headings inside fenced code blocks are ignored so a hash in a code sample is never mistaken for a heading.

markdownheadingslintdocumentation

How to use Markdown Heading Hierarchy Validator

  • 1.Paste a Markdown document, or try one of the sample snippets to see the output shape.
  • 2.Review the parsed heading list alongside any issues, each one anchored to the line number where it occurs.
  • 3.Fix the flagged headings in your source document and re-check, since this tool only reports issues, it doesn't rewrite the document for you.

Frequently asked questions

Does this check Setext-style headings underlined with === or ---?
No, only ATX-style headings written with one to six leading # characters are recognized, matching the sibling Markdown Table of Contents Generator.
Why does it flag more than one H1?
A document conventionally has exactly one top-level heading. A second H1 usually means a section was meant to be an H2, which this tool flags so it does not slip past review.
What counts as a skipped level?
Any jump deeper than one level at a time, such as an H1 followed directly by an H3 with no H2 in between. Going back up to a shallower level, like H3 back to H1, is never flagged.
Is my document sent anywhere?
No, scanning runs entirely in your browser (or in your own process via the SDK/API), with nothing uploaded.

Use via API, SDK, or MCP

cURL# Free: 1,000 req/day · Pro: 10,000 req/day
curl -X POST https://api.utilix.tech/v1/tools/markdown-heading-hierarchy-validator \
  -H "Authorization: Bearer utx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Title\n\n### Too Deep\n"}'

Get an API key from your dashboard · Full API docs →

Related tools

Markdown Code Fence Language Tag ValidatorScan a Markdown document's fenced code blocks and flag a missing, unknown, or inconsistently-cased language tagCodeMarkdown Link Reference ExtractorExtract reference-style Markdown links ([text][ref]) and their [ref]: url definitions, flagging unresolved references and unused definitionsCodeMarkdown Table of Contents GeneratorScan a Markdown document's ATX headings and build a nested table of contents with GitHub-style anchor slugs, disambiguating duplicate headings automaticallyCode