Create a Simple MDX Table of Contents in Contentlayer

A Table of Contents is a common feature that we usually see in articles. This feature makes it much easier for web visitors to navigate between each section of a webpage article. Here I’m going to show you how to generate a table of contents automatically on your MDX Contentlayer blog.

Install rehype-toc plugins

The first step is to install the rehype-toc plugin created by jsdevtools. You can install it with this command.

1
npm install @jsdevtools/rehype-toc

You’ll probably want to install unified, rehype-parse, rehype-stringify, and rehype-slug as well.

1
npm install unified rehype-parse rehype-stringify rehype-slug

Edit Contentlayer configuration

Next, you need to add rehype-toc inside your Contentlayer configuration files. Here’s an example.

1
import rehypeToc from "@jsdevtools/rehype-toc";
2

3
const contentLayerConfig = makeSource({
4
  contentDirPath: "src/contents",
5
  documentTypes: [Post, Project],
6
  mdx: {
7
    remarkPlugins: [remarkGfm],
8
    rehypePlugins: [
9
      rehypeCodeTitles,
10
      rehypeSlug,
11
      [rehypeToc, { customizeTOC }], // add rehypeToc and customization
12
    ],
13
  },
14
});

Customize your ToC

If you see the code snippet where I add rehype-toc to my rehypePlugins, I also define my own customization for the ToC. Here’s the code.

1
const customizeTOC = (toc: RehypeElement): RehypeElement | null => {
2
  try {
3
    const { children } = toc;
4
    const childrenOfChildren = children?.[0]?.children;
5
    if (!children?.length || !childrenOfChildren?.length) return null;
6
  } catch (e) {}
7
  return {
8
    type: "element",
9
    tagName: "div",
10
    properties: { className: "toc" },
11
    children: [
12
      {
13
        type: "element",
14
        tagName: "p",
15
        properties: { className: "title" },
16
        children: [
17
          {
18
            type: "text",
19
            value: "Table of Contents",
20
          },
21
        ],
22
      },
23
      ...(toc.children || []),
24
    ],
25
  };
26
};

This customization will wrap our ToC with a div element that has the class toc. Inside this div, we have a text element with a p tag that has the title class. Below this p tag, we will see our ToC content.

And that’s it. Now when you create new MDX content, the ToC will appear at the top of your MDX content body. You don’t need to add any extra code to your MDX content to display the ToC, because it generates automatically for all your MDX content.