Free tool · works now
Markdown Table of Contents Builder
Generate clean, linked tables of contents from your Markdown notes with custom anchor styles and depth limits.
Runs 100% in your browser. Paste any Markdown document to extract structured headings, isolate code fences, and generate clean, copyable tables of contents for GitHub or Obsidian.
- [1. System Overview](#1-system-overview)
- [1.1 Local Filesystem Invariants](#11-local-filesystem-invariants)
- [1.1.1 File Naming Conventions](#111-file-naming-conventions)
- [1.1.2 Frontmatter Metadata](#112-frontmatter-metadata)
- [1.2 Storage Engine Architecture](#12-storage-engine-architecture)
- [2. Audio Processing Pipeline](#2-audio-processing-pipeline)
- [2.1 Ring Buffer Implementation](#21-ring-buffer-implementation)
- [2.2 Whisper On-Device Model](#22-whisper-on-device-model)
- [3. Security & Privacy Guarantees](#3-security-privacy-guarantees)
- [3.1 Sandboxing & TCC Entitlements](#31-sandboxing-tcc-entitlements)
- [3.2 Zero-Telemetry Validation](#32-zero-telemetry-validation)
- [4. Migration & Export Compatibility](#4-migration-export-compatibility)
- [4.1 Obsidian Compatibility](#41-obsidian-compatibility)
- [4.1 Migration & Export Compatibility](#41-migration-export-compatibility)Why manual tables of contents in Markdown break easily
Long-form Markdown documents—such as technical architecture design records, product requirements documents, engineering onboarding runbooks, and comprehensive meeting minutes—require clear navigation aids. Readers need to scan high-level topics quickly and jump directly to relevant sections without endless manual scrolling.
However, maintaining a table of contents by hand is famously brittle. Whenever a section is renamed, reordered, or deleted, manual links immediately break or drift out of date. Furthermore, computing correct anchor tags by hand is prone to errors: different Markdown renderers use conflicting rules for converting punctuation, accented characters, numbers, and spaces into anchor targets. This free tool automates heading extraction and link generation entirely inside your browser, ensuring zero broken internal anchors.
Understanding anchor slug formats across platforms
Not all Markdown platforms resolve internal anchor links the same way. Selecting the right format is critical depending on where your document is hosted and rendered:
- GitHub Flavored Markdown (GFM): GitHub processes heading text by converting characters to lowercase, stripping all ASCII punctuation (commas, periods, colons, question marks), converting spaces into hyphens, and resolving duplicate headings with an appended counter (e.g.
#overviewfollowed by#overview-1). - Obsidian Internal WikiLinks: In Obsidian vaults and compatible note applications like Oyma, heading links can be written as internal wikilinks using double brackets (
[[#Heading Name]]). Obsidian matches the raw heading title directly, preserving original casing, punctuation, and spaces without requiring kebab-case slugification. - Standard CommonMark Anchors: CommonMark specifications recommend standard percent-encoded URLs or clean hyphenated slugs. This tool lets you switch between GitHub kebab-case slugs, native Obsidian wikilinks, or standard URL-encoded anchor references with a single click.
Isolating fenced code blocks and false headings
One of the primary failure modes of naive heading parsers is mistakenly treating lines inside code blocks as document headings. In languages like Python, Bash, YAML, Ruby, and Elixir, comments begin with a hash symbol (#). A snippet containing configuration comments or shebang lines will be falsely indexed as an H1 or H2 heading by unhardened scripts.
Our builder includes stateful fence tracking for triple backticks (```) and tildes (~~~), as well as multi-line HTML comments (<!-- -->). Any hash markers occurring within these boundaries are strictly ignored, ensuring that only genuine editorial headings appear in your navigation outline.
Best practices for Markdown heading hierarchies
To ensure both visual clarity and screen reader accessibility, technical documents should maintain strict heading hierarchies:
- Reserve H1 for the document title: Use a single top-level heading (
# Title) at the very start of the file. Your table of contents should typically begin at H2 (## Section) to avoid redundant self-referential links. - Never skip heading levels: Avoid jumping directly from an H2 section to an H4 subsection without an intervening H3. Skipping levels confuses automated screen readers and disrupts outline formatting. This tool includes automated hierarchy linting to flag skipped levels in real time.
- Limit TOC depth to what aids navigation: Including H5 and H6 subheadings often produces noisy, overly dense lists that hinder fast scanning. Restricting your table of contents to H2 through H4 provides the optimal balance of comprehensive detail and effortless readability.
Managing notes and documentation in Oyma
At Oyma, we believe technical notes should remain clean, portable, and under your complete control. Our macOS application saves your documents as standard plain-text Markdown files on your local drive, compatible with our Obsidian vault guidelines. Explore our other free utilities, including the Markdown word counter and Markdown table formatter, to streamline your daily writing and meeting workflows.
Questions
What is a Markdown table of contents and how do anchor links work?
A table of contents in Markdown is an indented list of section headings where each item links to its corresponding heading anchor tag in the document. In GitHub Markdown and CommonMark, clicking an anchor link jumps the reader directly to that section heading in the rendered note or repository view.
How does GitHub slugify heading anchors compared to Obsidian?
GitHub converts heading text to lowercase, strips punctuation characters, replaces whitespace sequences with hyphens, and appends incrementing numeric suffixes (-1, -2) to resolve duplicate headings. Obsidian supports both standard percent-encoded Markdown links and native internal wikilinks ([[#Heading Name]]), preserving original casing and spaces.
Why does this tool ignore headings inside triple-backtick code fences?
Technical notes and code documentation frequently contain comment lines starting with hash characters inside code snippets (such as # Python comments or #!/bin/bash shebangs). Naive tools mistakenly parse these lines as section headings. Our parser isolates code fences and HTML comments completely.
How does the builder handle duplicate headings in the same note?
When duplicate headings occur—such as multiple "Summary" or "Next Steps" sections across meeting agendas—the tool tracks heading frequencies and generates disambiguated anchor slugs (#summary, #summary-1) matching GitHub and CommonMark specification rules.
Does this tool transmit my confidential notes or document outlines over the internet?
No. The entire heading extraction and link generation engine executes strictly in your local browser tab. No document text, headings, or structural outlines are ever transmitted, logged, or uploaded to any remote server.
Want long-form notes that navigate effortlessly?
Full Obsidian vault compatibility, fast heading navigation, and private on-device meeting recording in Oyma.