mirror of
https://github.com/m-kk/toc.git
synced 2026-07-22 06:44:17 +00:00
108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# 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
|
||
|
||
<a href="https://www.buymeacoffee.com/mattkk" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
|
||
|
||
## 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
|
||
```markdown
|
||
---
|
||
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):
|
||
|
||
```yaml
|
||
---
|
||
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
|
||
|
||
```bash
|
||
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](https://github.com/m-kk/toc/issues)
|
||
|
||
## Support
|
||
|
||
If you find this plugin useful, consider a donation! Thank you!
|
||
|
||
<a href="https://www.buymeacoffee.com/mattkk" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
|