satteri-toc

A Sätteri plugin to generate a table of contents.

Install

npm install satteri-toc

Use

import { markdownToHtml } from "satteri";
import { toc } from "satteri-toc";

const { html } = markdownToHtml("## Hello World", {
  mdastPlugins: [toc(options)],
});

With Astro 7:

// astro.config.mjs
import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";
import { toc } from "satteri-toc";

export default defineConfig({
  markdown: {
    processor: satteri({
      mdastPlugins: [toc(options)],
    }),
  },
});

API

toc(options?)

Returns an array of Sätteri MdAst plugin factories, whose result can be passed in the mdastPlugins array.

options: TocOptions

options.prefix?: string

The prefix to add to all heading links. The default is an empty string.

options.slugger?: (text: string) => string

Function used to convert a heading's text into an id. Uses github-slugger by default.

options.matcher?: (text: string) => boolean

Function that matches contents of existing headings in the document to append the table of contents. The default is a case-insensitive match of "table of contents" and "toc" strings. It is used to match only the first heading that satisfies the condition. If no heading is matched, the fallback case is used instead.

options.fallback?

The fallback heading for the table of contents. When no existing heading in the document is matched, a heading is created at the very top with these settings and the table of contents is rendered there. If there are no headings in the document, the fallback is skipped.

options.fallback.text: string

Text content of the fallback heading. Default is "Table of Contents".

options.fallback.level: 1 | 2 | 3 | 4 | 5 | 6

Level of the fallback heading (corresponding to h1, h2, etc). Default is 1.

Examples

View the demo Astro project.

With fallback

See markdown source

With matcher

See markdown source

License

MIT © Aryaveer Singh Rawat