help readers find their way know each page @mdsvex/plugin-toc
Table of contents
Table of contents, the headings of a document as data and a component that lists them
Install
pnpm add -D @mdsvex/plugin-toc@next Turn it on
import { toc } from '@mdsvex/plugin-toc';
mdsvex({ heading_ids: true, plugins: [toc()] }); What it reads
::toc[On this page]heading ## Headingowns toc · acts on headings · reads the whole document
An example
# Guide ::toc[On this page] ## Install ### With pnpm ## Configure
Guide
Install
With pnpm
Configure
Leaves the headings of each document in its plugin data, as a flat list in the order they are written:
import Page, { plugin_data } from './getting-started.svx';
plugin_data.toc.headings;
// [
// { depth: 2, id: 'install', text: 'Install', position: { start, end } },
// { depth: 3, id: 'with-pnpm', text: 'With pnpm', position: { start, end } },
// { depth: 2, id: 'configure', text: 'Configure', position: { start, end } }
// ]text is what a reader sees, without markup, and position is where the heading is in the source. A document with nothing to list has no toc key. toc_tree(headings), from the same package, nests the list, each heading under the nearest less deep one before it.
It needs heading_ids. The plugin makes no ids of its own. With the option off, the compile of a document that has a heading to list fails with a TocError. A heading left without an id, such as ## {title}, is left out with a warning.
toc({
min_depth: number = 2,
max_depth: number = 3
});The defaults leave out the # title of the page and anything below ###. To leave one heading out, put a <!-- no-toc --> comment in it. It keeps its id:
## Changelog <!-- no-toc -->Every other markdown heading inside the depths is listed, wherever it is written. The headings of steps are listed. The headings that start a tab are labels, not headings, and are not. The build warns about a heading that skips a level, such as a ### straight after a #.
The package ships a component that renders the list, nested. A template gives it the data:
<script>
import Toc from '@mdsvex/plugin-toc/Toc.svelte';
let { plugin_data, children } = $props();
</script>
<aside>
<Toc headings={plugin_data?.toc?.headings} aria-label="On this page" />
</aside>
<main>{@render children()}</main><nav aria-label="On this page" class="toc">
<ul>
<li>
<a href="#install">Install</a>
<ul>
<li><a href="#with-pnpm">With pnpm</a></li>
</ul>
</li>
<li><a href="#configure">Configure</a></li>
</ul>
</nav>It takes min_depth and max_depth to narrow the list, a label snippet, and passes anything else to the <nav>. It needs Svelte 5.20 or later and ships no styles.
::toc, on a line of its own, renders the same component in the document:
# Getting started
::toc[On this page]
## InstallThe brackets are its label, ::toc(max_depth=2) narrows it, and any other arg is an attribute of the <nav>. It lists the whole document, the headings after it as well: the plugin fills it in once the document is parsed and its ids are set. While a document streams, nothing is shown in its place until the stream ends. A ::toc with nothing to list renders nothing, and the build says so.