Skip to main content

Adding a table of contents


Goal #

To easily add a table of contents for longer posts especially traces.

Which library should I pick? #

  • So there are a lot of table of contents markdown-it plugins (26 at the time of writing).

  • Let's try: markdown-it-toc-done-right. The pitch includes security, HTML5 semantic correctness. A bit pedantic, but probably the right kind.

  • Ah, looks like you should also get markdown-it-anchor (turns out I already did). Then I should also get markdown-it-attrs so I can override the heading id (might also be useful for lots of other little bits).

pnpm install --save-dev markdown-it-toc-done-right markdown-it-attrs
// eleventy.config.js
const markdownItAttrs = require("markdown-it-attrs");
const markdownItTOC = require("markdown-it-toc-done-right");
// ...
eleventyConfig.amendLibrary("md", (mdLib) => {
    mdLib.use(markdownItTOC, { listType: "ul" });
    // ...

Then just slap a [[toc]] tag in the markdown and we're good to go.