Creating a Top-Level Table of Contents with Bundler Imports in MDX

[ProchaLu]

I’m trying to build a top-level Table of Contents (TOC) in a parent MDX file that imports other MDX files as components. I’m using rehype-toc to generate the TOC. However, I’m encountering two problems:

• When importing an MDX file into a parent MDX, the TOC for each nested MDX file is being generated separately, leading to multiple TOCs on the same page
• The subheaders within the imported MDX components do not get added to the parent MDX file’s TOC, causing them to be excluded from the overall TOC structure

Expected Behavior:

The parent MDX file should generate a single, unified TOC that includes all headers, including those from nested MDX components

Actual Behavior:

Separate TOCs are generated for each MDX file and the parent TOC does not include headers from imported MDX components

Assumption:

It seems that MDX might be processing each .mdx file independently and is unaware of the larger page structure when components are imported.

Code Example

Parent MDX File:

import SubPage from './subpage.mdx';

# Main Page Title

## Section 1
Some content here.

<SubPage />

## Section 2
More content here.

Sub MDX File:

# SubPage Title

## SubSection 1
Subpage content.

## SubSection 2
More subpage content.

Resulting TOC:

Main Page Title
- Section 1
- Section 2

Expected TOC:

Main Page Title
- Section 1
- SubPage Title
  - SubSection 1
  - SubSection 2
- Section 2

Workaround attempt

To address these issues, I am experimenting with a recursive function to gather the full MDX content, including nested MDX files:

function recursiveMap(
  children: React.ReactNode,
  fn: (child: React.ReactElement) => any,
): any {
  return React.Children.map(children, (child) => {
    if (!React.isValidElement(child)) {
      return child;
    }

    if (child.props.children) {
      recursiveMap(child.props.children, fn);
    }

    return fn(child);
  });
}

I attempt to extract headers from this compiled content to create a unified TOC. However, I am encountering issues where the content type in nested MDX files is always undefined:

  {
    '$$typeof': Symbol(react.transitional.element),
    type: 'h2',
    key: null,
    props: { id: 'test', children: [Object] },
    _owner: { name: 'test', env: 'Server', owner: [Object] },
    _store: {}
  },
  {
    '$$typeof': Symbol(react.transitional.element),
    type: undefined,
    key: null,
    props: {},
    _owner: { name: 'test', env: 'Server', owner: [Object] },
    _store: {}
  },

Questions:

• Is there a way to configure rehype-toc or a similar plugin to generate a unified TOC that spans across nested MDX files?
• Are there any official recommendations or best practices for generating a unified TOC when dealing with nested MDX files?
• How can I resolve the issue with content type being undefined in the recursive function and correctly extract headers from nested MDX files?

[wooorm]

Hey!

Is there a way to configure rehype-toc or a similar plugin to generate a unified TOC that spans across nested MDX files?

This is impossible.
Your assumption is correct.
You’re talking about React here.
Which is evaluated somewhere, the client typically.
It generates different things for different users, or based on a different timestamp, or anything really. Different stuff when you’re logged in or not.
rehype-toc has access to the AST, before all that. Not the evaluated final result that a particular user right now sees.

Are there any official recommendations or best practices for generating a unified TOC when dealing with nested MDX files?

There is not one particular recommendation that I have for everybody, no.
What I would recommend you, is also dependent on more info: you abstracted your use case, which is nice, but to better help you, I’d appreciate it if you can expand on why you are doing what you are doing?

How can I resolve the issue with content type being undefined in the recursive function and correctly extract headers from nested MDX files?

There are several steps missing between that abbreviated code you showed, and how you are actually using it. I need to know those steps before I can answer this.

[ProchaLu]

How can I resolve the issue with content type being undefined in the recursive function and correctly extract headers from nested MDX files?

After some investigation, I found out that React.children.map has a critical drawback of not showing the rendered children of children elements

Alternative

Creating a React Context with a tableOfContents nested object, wrapping <MDXContent /> in a React Context provider and then setting values from each of the h2, h3, h4, h5, h6 replacement elements in mdx-components.tsx

[ProchaLu]

@wooorm , thx for the quick answer

you abstracted your use case, which is nice, but to better help you, I’d appreciate it if you can expand on why you are doing what you are doing?

The main goal here is reusability across different MDX files. I have certain pieces of content that I want to use in different places, so I’ve encapsulated this content in a component (MDX file) for easier maintenance and reuse.

Example Structure

//parent1.mdx
import { MyComponent } from './my-component.mdx'

# Parent 1

lorem ipsum

<MyComponent />

//parent2.mdx
import { MyComponent } from './my-component.mdx'

# Parent 2

lorem ipsum

<MyComponent />

//my-component.mdx

# My Component

lorem ipsum

In our case, the content of the child component includes a header and a paragraph.

The challenge for me is how I can get the headers of the child component to be displayed in the TOC of the parent component.

How can I resolve the issue with content type being undefined in the recursive function and correctly extract headers from nested MDX files?
There are several steps missing between that abbreviated code you showed, and how you are actually using it. I need to know those steps before I can answer this.

I think I already found out that this is not possible in my comment above. React is not showing the rendered children of children elements.

[wooorm]

Right, thanks, that’s a bit of info. But it doesn’t provide much. Like, it doesn‘t tell me why you couldn‘t do it with jQuery. What tools are you using. Are you generating headings dynamically in your reusable components or not. What actual documents do you have? How often is it reused? Why not copy/paste the document twice, with a comment saying to update the other as well? Why do you even have duplicate content, are you not concerned about SEO problems, or that readers re-read the same stuff several times? What about the heading structure (say theres a h3 in the reused component, what if it’s “included” “under” a h3?)

As mentioned earlier, I can still come up with many different ways to go about this, there is not one particular thing I suggest. I’d now lean on: do not put important headings in the reusable component.

[ProchaLu]

Why couldn't you do it with jQuery?

JQuery is great, but I am using Next.js with React Server Components, and jQuery operates outside of React, which can lead to issues with state management and UI consistency.

What tools are you using?

I am using Next.js with React Server Components and MDX for content management, making it easier to manage content and structure in a way that's both developer-friendly and flexible.

Are you generating headings dynamically in your reusable components or not?

No, the headers are static and defined in the MDX files.

What actual documents do you have?

We have some MDX files that contain the content of our curriculum modules.

How often is it reused?

The components and content are reused across multiple pages and sections, and we aim to minimize duplicate content as much as possible, but in cases where similar content needs to be presented in different contexts, we use components to encapsulate and reuse that content.

Why not copy/paste the document twice, with a comment saying to update the other as well?

This seems like a bad developer experience and can lead to inconsistencies, outdated content, and it increases the maintenance overhead.

What about the heading structure (say there’s an h3 in the reused component, what if it’s “included” “under” an h3)?

The heading structure is consistent across all components and pages, and we aim to maintain a clear and logical hierarchy to ensure a good user experience and SEO. The component is not automatically adjusting the heading structure based on the parent component, but when creating a custom TOC, we can implement checks to catch any inconsistencies or broken hierarchies.

---

The focus on my approach is to find a way to generate a unified TOC that spans across nested MDX files.

I know I can create the header in the parent component, but I want to avoid this, and find a solution that allows me to keep the headers in the child components and still have them show up in the parent component's TOC.

Currently, I’m working on retrieving headers from the context and adding them to the TOC. I know that this is not a server component but I give it a try.

[wooorm]

This seems like a bad developer experience and can lead to inconsistencies, outdated content, and it increases the maintenance overhead.

I’d push back against this, copy/pasting is very quick and simple; premature optimization is a thing too; and outdated content is going to be a problem with any content that’s maintained over years

---

If I search for “react table of contents” online, I do find everyone doing useEffect(() => { const headingElements = Array.from(document.querySelectorAll("h2, h3")); …; why not do that?

[karlhorky]

@ProchaLu created a top-level table of contents PR based on React Context in mdx-tricks over here, in case it's helpful for anyone:

• https://github.com/karlhorky/mdx-tricks#top-level-table-of-contents-from-imported-mdx-headings-nextjs

Allows for imports of other MDX files, without resorting to use of useEffect or similar.

Even better would be a server-computed version (eg. React Server Components or similar), maybe another time...