Plugins Table of contents

help readers find their way know each page @mdsvex/plugin-toc@0.1.0-next.1

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

owns toc · acts on headings · reads the whole document

An example

You write
# Guide

::toc[On this page]

## Install

### With pnpm

## Configure

You get

Guide

Install

With pnpm

Configure

Build-time preview.

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]

## Install

The 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.

Options, from its types 2

min_depth?: number
The least deep heading in the table, 2 by default, which leaves the title of the page out
max_depth?: number
The deepest heading in the table, 3 by default

mdsvex, markdown with Svelte in it. MIT licence.