remark-simple-toc

Simple remark plugin that generates a compact table of contents (ToC) for Markdown documents.

Overview

• Generates a ToC from headings h2-h6. Main heading h1 is usually used only once throughout the whole document and therefore should not appear in a ToC.
• The ToC starts from the first h2 – headings before the first h2 are ignored.
• Progressive nesting: h3 becomes a child of the latest h2, h4 of the latest h3, ...
• If you miss a heading level, it's okay – e.g. h5 is nested under the latest h2 if h3 and h4 are not present.
• Uses existing headings' id to create anchor links. If no id is present, the entry is rendered as plain text (no link). (More on this in Recommendation & Usage)
• If a heading is empty, it is still added to the ToC with text -EMPTY-HEADING-.
• All headings in the ToC are progressively numbered.
• Outputs a small HTML structure with a checkbox toggle and labelled count spans for numbering.
• If the page contains no h2 heading, no ToC will be generated. (All other heading levels are allowed).
• The HTML structure is either appended at the beginning of the processed Markdown content or right before first <section> element.
• Astro only: you can turn off the generation of the ToC for certain pages.

Installation

Install with your favorite package manager. Example (Bun):

bun install remark-simple-toc

Recommendation & Usage

It is advised for this packaged to be used with e.g. remark-simple-slug or another package that adds slugified id properties to the Markdown AST.

That is because the id can be present in the HTML DOM but defaultly are not present in the Markdown AST. Therefore, you need another remark package that adds them. That package needs to be called before this one.

You could also benefit from the package remark-normalize-headings that makes sure there is only on h1 element and therefore the ToC gets generated correctly. This plugin could be useful if you deal with a lot of suboptimally formatted Markdown content.

Generic Example

import { unified } from "unified"
import remark_parse from "remark-parse"
import remark_rehype from "remark-rehype"

import toc from "remark-simple-toc"
import slug from "remark-simple-slug"

const file = await unified()
  .use(remark_parse)
  // needs to be in order slug -> toc
  .use(slug) // optional slugifier; required for links in ToC
  .use(toc, "My lovely ToC") // optional string sets the ToC title; default is "Contents"
  .use(remark_rehype)
  .process(...)

Have a look here to find more details about remark.

Astro Example

// astro.config.mjs
import slug from "remark-simple-slug"
import toc from "remark-simple-toc"

export default defineConfig({
  ...,
  markdown: {
    ...,
    remarkPlugins: [
      ...,
      // needs to be in order slug -> toc
      slug, // optional for links
      [toc, "My lovely ToC"], // or just add 'toc' and the title will default to 'Contents'
      ...
    ],
    rehypePlugins: [ ... ],
    ...
  },
  ...
});

As mentioned above, in Astro you can turn off the generation of a ToC for certain pages. This is has to be done manually for each page. By default the ToC gets generated for every page that contains at least one <h2> element.

To turn off ToC generation, simply add toc: false to the frontmatter of given .md file as shown below:

---
title: Lorem Ipsum
release_date: ...
...
toc: false
---
## Level two heading
This page will have no rendered ToC thanks to the `toc: false` in frontmatter.

If the file contains no <h2> heading, no set up is needed – the ToC won't be generated (the Markdown file can still contain h1 and h3-h6)

Possible future improvements

• Add online demo of how the ToC acts.
• Add example CSS styling.
• Choose where the ToC gets appended.
• Set a lower bound on which levels of headings get included in the ToC.

License

MIT © Adrián Zámečník