m-kk_toc/README.md

Table of Contents Generator

An Obsidian plugin that generates a table of contents from your note's headings — no visible HTML markers, tracked through a small YAML frontmatter key instead.

Why This Plugin?

• No visible markers: unlike plugins that insert HTML comments (<!-- TOC -->) into your source view, the TOC section is identified by its heading and tracked via frontmatter
• Safe updates: the TOC section is only ever matched by its heading title (your configured title or common ones like "Contents"), so regenerating never touches other sections of your note
• Idempotent: regenerating an unchanged note produces byte-identical content — safe to combine with sync and auto-formatting plugins
• Wikilink navigation: entries are [[#Heading|Heading]] links that work in preview and live preview

Features

• Positioning: the TOC is inserted after the last H1 heading, or directly after frontmatter (or at the top) when there is no H1
• Auto-update: optionally refresh an existing TOC automatically as the note changes (debounced, only for notes that already have one)
• Heading depth control: exclude H1 headings and cap depth (1–6)
• Pattern exclusion: skip headings matching regular expressions (validated in settings)
• Link options: clickable wikilink entries or plain text
• Custom title: personalize the TOC heading
• Removal command: cleanly delete the TOC section and its frontmatter key

Installation

From Obsidian Community Plugins

1. Open Obsidian Settings → Community Plugins
2. Search for "Table of Contents Generator"
3. Install and enable the plugin

Manual Installation

1. Download the latest release from GitHub
2. Extract files to .obsidian/plugins/table-of-contents-generator/
3. Enable the plugin in Community Plugins settings

Usage

1. Open any note with headings
2. Run the command Generate table of contents or click the ribbon icon
3. Run it again at any time to refresh, or enable auto-update in settings

Generated TOC Example

---
toc:
  generated: true
---
# My Note

## Table of Contents

- [[#Introduction|Introduction]]
  - [[#Getting Started|Getting Started]]
- [[#Advanced Features|Advanced Features]]

## Introduction
...

Duplicate heading names are listed, but only the first occurrence is linked — Obsidian wikilinks cannot address later occurrences of the same heading text.

Settings

• Table of contents title (default: "Table of Contents")
• Exclude level 1 headings (default: on)
• Maximum heading depth (1–6, default: 4)
• Include links (default: on)
• Exclude patterns: one regex per line; invalid patterns are flagged and not saved
• Auto-update table of contents: refresh an existing TOC whenever the note changes on disk (default: off)

Commands

• Generate table of contents: insert or refresh the TOC in the active note
• Remove table of contents: delete the TOC section and its toc frontmatter key

Technical Details

The plugin marks TOC-managed notes with a minimal frontmatter key, written via Obsidian's processFrontMatter API (your other frontmatter is never rewritten by hand):

---
toc:
  generated: true
---

The TOC section itself is located by matching an H2 against your configured title or the common aliases "Table of Contents", "TOC", "Contents", "Index", and "Outline" — headings inside code fences are ignored. Requires Obsidian 1.7.2+.

Development

npm install
npm run dev     # watch build
npm test        # vitest unit tests
npm run build   # typecheck + production build

Core logic lives in src/ as pure, unit-tested functions (toc-section.ts, toc-generator.ts, heading-filter.ts); main.ts contains only Obsidian wiring.

Feedback

• Bugs, Issues, & Feature Requests

Support

If you find this plugin useful, consider a donation! Thank you!