Adding a table of contents

• 2023-05-18
• trace,
• markdown,
• eleventy

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(markdownItAttrs);
    mdLib.use(markdownItTOC, { listType: "ul" });
    // ...
};

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