Free tool · works now

Heading Anchor Checker

Audit Markdown heading links and identify broken or ambiguous anchors across GitHub and Obsidian.

Runs 100% in your browser. Audit Markdown heading links, inspect slug compatibility across GitHub and Obsidian, detect typos, and export formula-guarded audit reports.

7Headings
9Anchor links
6Valid
1Near matches
0Ambiguous
2Broken
Source Markdown document1136 chars
Link resolution auditAudited
LineTarget AnchorStatusResolution / Suggested Fix
6#system-requirementsValidResolved to heading on Line 16: "System Requirements".
7#storage-benchmarksValidResolved to heading on Line 19: "Storage Benchmarks".
8#configurationValidResolved to heading on Line 22: "Configuration".
9storage-guide.md#database-engineValidCross-file anchor target (storage-guide.md#database-engine). Cannot audit without external file content.
10#storge-benchmarksNear matchPossible typo (distance: 1). Closest heading on Line 19: "Storage Benchmarks".
Suggested: #storage-benchmarks
11#missing-section-targetBrokenNo heading matching anchor "#missing-section-target" was found in this document.
12[[#Quick Navigation]]ValidMatches heading on Line 5: "Quick Navigation".
13[[#Storage Benchmarks|Performance Benchmarks]]ValidMatches heading on Line 19: "Storage Benchmarks".
14[[#Unwritten Chapter]]BrokenNo heading matching anchor "#Unwritten Chapter" was found in this document.
Document Headings Inventory7 detected
LevelLineHeading TextGenerated Anchor SlugUniqueness
H11Storage Engine Architecture#storage-engine-architectureUnique
H25Quick Navigation#quick-navigationUnique
H216System Requirements#system-requirementsUnique
H219Storage Benchmarks#storage-benchmarksUnique
H322Configuration#configurationUnique
H325Configuration#configuration-1Duplicate (#configuration-1)
H233Data Integrity Guarantees#data-integrity-guaranteesUnique
Formula-Guarded CSV ExportSpreadsheet ready
"Type","Line","Text","Anchor / Target","Status","Details"
"Heading","Line 1","H1: Storage Engine Architecture","#storage-engine-architecture","Unique","First occurrence"
"Heading","Line 5","H2: Quick Navigation","#quick-navigation","Unique","First occurrence"
"Heading","Line 16","H2: System Requirements","#system-requirements","Unique","First occurrence"
"Heading","Line 19","H2: Storage Benchmarks","#storage-benchmarks","Unique","First occurrence"
"Heading","Line 22","H3: Configuration","#configuration","Unique","First occurrence"
"Heading","Line 25","H3: Configuration","#configuration-1","Duplicate (#configuration-1)","Duplicate occurrence 2"
"Heading","Line 33","H2: Data Integrity Guarantees","#data-integrity-guarantees","Unique","First occurrence"
"Markdown Link","Line 6","System Requirements","#system-requirements","valid","Resolved to heading on Line 16: ""System Requirements""."
"Markdown Link","Line 7","Storage Benchmarks","#storage-benchmarks","valid","Resolved to heading on Line 19: ""Storage Benchmarks""."
"Markdown Link","Line 8","Duplicate Subsystems","#configuration","valid","Resolved to heading on Line 22: ""Configuration""."
"Markdown Link","Line 9","Cross Note Reference","storage-guide.md#database-engine","valid","Cross-file anchor target (storage-guide.md#database-engine). Cannot audit without external file content."
"Markdown Link","Line 10","Typo in Anchor","#storge-benchmarks","near-match","Possible typo (distance: 1). Closest heading on Line 19: ""Storage Benchmarks"". (Suggested fix: #storage-benchmarks)"
"Markdown Link","Line 11","Broken Link","#missing-section-target","broken","No heading matching anchor ""#missing-section-target"" was found in this document."
"Wikilink","Line 12","Quick Navigation","[[#Quick Navigation]]","valid","Matches heading on Line 5: ""Quick Navigation""."
"Wikilink","Line 13","Performance Benchmarks","[[#Storage Benchmarks|Performance Benchmarks]]","valid","Matches heading on Line 19: ""Storage Benchmarks""."
"Wikilink","Line 14","Unwritten Chapter","[[#Unwritten Chapter]]","broken","No heading matching anchor ""#Unwritten Chapter"" was found in this document."

Why heading anchor links silently break in Markdown notes

Internal heading links are fundamental to navigating technical documentation, research notes, and personal knowledge bases. When a table of contents or inline note references a specific section with [Architecture](#architecture-overview) or [[#Storage Engine]], readers expect an instant jump to the relevant material.

However, heading anchor resolution is among the most inconsistent specifications in the Markdown ecosystem. Unlike HTML where element IDs are explicitly authored, Markdown processors automatically synthesize anchor IDs from arbitrary heading prose. Differences in punctuation filtering, whitespace handling, duplicate suffixes, and case conversion frequently turn working navigation into silent 404 dead ends.

Anchor slugification rules across major platforms

Each major toolchain generates anchor identifiers using distinct transformation heuristics:

  • GitHub Flavored Markdown (GFM): Converts headings entirely to lowercase, replaces spaces with hyphens, and removes punctuation characters such as periods, colons, question marks, and parentheses. Consecutive hyphens are collapsed. If duplicate headings exist, GitHub appends an integer suffix (e.g. #installation, #installation-1, #installation-2).
  • Obsidian Note Vaults: Obsidian supports two distinct reference patterns. Standard wikilink anchors ([[Note#Heading Title]]) resolve case-insensitively against the exact literal heading text. When authored as standard Markdown links ([text](#heading-title)), Obsidian follows standard kebab-cased slugs. If duplicate headings occur, wikilink targets resolve to the first matching instance in the file.
  • CommonMark and Pandoc: Retains unicode character sets across international languages while stripping Latin punctuation. Underscores may be preserved depending on processor configuration.

Disambiguating duplicate headings

A frequent source of broken navigation in long documentation is recurring section titles. Multi-part documents often feature repetitive subheadings such as:

## Component Alpha
### Configuration
### Error Handling

## Component Beta
### Configuration
### Error Handling

In this scenario, a naive link to [Config](#configuration) under Component Beta will incorrectly jump the reader back to Component Alpha's configuration block. GFM requires linking explicitly to #configuration-1 to access the second block. The Heading Anchor Checker audits your entire document hierarchy, isolates duplicate collisions, and reveals exactly which suffix is required for predictable routing.

Audit checklist before publishing notes or documentation

Before committing Markdown files to a public repository, knowledge vault, or team wiki, verify these critical conditions:

  1. Verify Slug Format: Ensure internal Markdown links use lowercase kebab-case (e.g. #system-overview rather than #System-Overview or #system_overview).
  2. Audit Duplicate Headings: Either disambiguate duplicate titles with parent qualifiers (e.g. "Alpha Configuration" vs "Beta Configuration") or verify proper integer suffixing.
  3. Isolate Code Snippets: Ensure that sample headings within fenced code examples are not referenced as document sections.
  4. Preserve Data Confidentiality: Never paste sensitive proprietary notes into cloud-based formatting services. Use local browser-memory processing.

Related documentation utilities

Explore companion local utilities for structuring Markdown vaults and notes:

Questions

How do heading anchors differ between GitHub, Obsidian, and CommonMark?

GitHub Flavored Markdown (GFM) strips punctuation, converts whitespace to hyphens, forces lowercase, and appends integer increments (-1, -2) to duplicate headings. Obsidian allows both raw text matching in wikilinks ([[#My Heading]]) and slugified anchor links. CommonMark and Pandoc follow similar kebab-case slugging with minor variations in unicode character retention.

Why do duplicate headings break internal document navigation?

When two or more sections share identical heading text (such as multiple "Configuration" or "Overview" subheadings), standard Markdown anchors become ambiguous. In GitHub, a link to `#configuration` always scrolls to the first occurrence, leaving the second heading unreachable unless disambiguated with `#configuration-1`.

How does the checker detect near matches and formatting typos?

The engine compares unresolved anchor links against known document headings using both normalized slug transformations and Levenshtein string distance. If an anchor differs only by underscores versus hyphens or contains a minor spelling slip, the tool suggests the exact valid anchor target.

Are code blocks and script snippets protected from false heading extraction?

Yes. The engine parses Markdown line-by-line and detects both triple-backtick and triple-tilde code fences. Any hashtag or link syntax inside code blocks is strictly ignored, preventing sample snippets from polluting your heading inventory.

Does this tool upload or transmit my private documentation?

No. All heading extraction, slug generation, link resolution, and CSV compilation execute entirely inside your browser memory. Closing or refreshing the page immediately purges all data from memory.

Want reliable Markdown navigation across your notes?

Complete Obsidian vault compatibility, plain text Markdown on disk, and private on-device notes in Oyma.

tools heading anchor checker downloadDownload for Mac

No account needed. Intel Mac build