Inline TOC

One table of contents that is live while you read, plain Markdown when you publish, and never goes stale.

Why this one

• Live and clickable. A toc code block builds the list from the note's headings and updates as you type. Repeated heading names go to the right heading.
• Plain Markdown for Publish and exports. The same list can be written between two comment markers, and it refreshes itself two seconds after you change a heading.
• Foldable, with the current section highlighted. Collapse the whole block or a single branch; the item for the section you are reading stands out.
• Reads your existing blocks. table-of-contents blocks written for Automatic Table of Contents work as they are, and a list made by Table of Contents can be adopted with one command.
• Careful with the details. Front matter, code, maths and comments never produce items; heading text with links or formatting is shown clean; every generated link is checked against Obsidian's own heading resolver.

Quick start

Run Insert table of contents from the command palette. It adds an empty block:

```toc
```

That is all: the block lists every heading, with the note's own title left out. Add options, one per line, to change it:

```toc
title: In this note
levels: 2-3
style: numbered
```

Live block options

One option per line: key: value, key = value or key value. Keys ignore case, dashes and underscores. A bare numbered works too. A bad value never stops the block: it shows a small note under the list and carries on.

The defaults for most of these are in the settings. skipH1: auto leaves out a first heading 1 when it is the only one, so the list does not start with the note's own title.

These Automatic Table of Contents names also work: minLevel, maxLevel, includeLinks, style: nestedList, nestedOrderedList and inlineFirstLevel. Both ```toc and ```table-of-contents are rendered.

Markdown table of contents (for Publish and export)

A live block is a code block, so Publish and exports do not show it as a list. Insert Markdown table of contents writes the list as text between two markers instead:

<!-- inline-toc -->
**Contents**

- [[#Intro]]
  - [[#Detail]]
- [[#Notes]]
<!-- /inline-toc -->

• The options go in the opening marker: <!-- inline-toc min=2 max=3 style=numbered title="In this note" -->. Only values that differ from the defaults are written.
• Everything between the markers is rewritten on refresh. Edit the marker, not the list.
• Refresh Markdown tables of contents refreshes every marked block in the note in one undo step. The command only appears in a note that has one.
• Keep up to date while editing (a setting, on by default) refreshes the lists two seconds after you change a heading. It never runs after an undo or redo, so undoing stays undoing, and never while your cursor is inside a list.
• Headings that share a name get a path ([[#Method#Notes|Notes]]) so each link goes to the right one.
• Switch table of contents between live and Markdown turns one into the other and keeps the options.

Commands

Every command is a single undo step.

Settings

Title, lowest and highest heading level, style, number format, whether to leave out the note title, headings to exclude, whether to strip numbers the headings already carry, the current-section highlight, starting collapsed, the frame, auto-refresh, link format (wikilinks or Markdown links), the title line, and the format for section lists.

Coming from another table-of-contents plugin

• Automatic Table of Contents: your blocks render as they are. Only one plugin can render a code block language, so disable it first (if Automatic Table of Contents loads first it keeps table-of-contents, and the settings tab says so).
• Table of Contents: run Adopt existing table of contents with the cursor in each list.
• Insta TOC: the same command turns its block into a marked list.

Styling

The block is a nav element with the class inline-toc. Themes and snippets can change --inline-toc-indent, --inline-toc-bg, --inline-toc-border, --inline-toc-radius, --inline-toc-link, --inline-toc-active, --inline-toc-number and --inline-toc-font-size. Style Settings can change the indent.

Accessibility

The block is a labelled nav with real lists. The collapse controls are buttons with aria-expanded, the current section carries aria-current="location", focus is visible, and on mobile every link and button is at least 32 px tall. Motion is off when the system asks for reduced motion.

Installation

In Obsidian, open Settings → Community plugins → Browse and search for "Inline TOC".

More plugins by Siulved54

All of them are in the community directory: Settings -> Community plugins -> Browse, then search for the name. Demos and install links for every one: the catalog.

Follow new plugins and updates on X: @luenpereza