TOC does not work when importing one MDX into another

[oriooctopus]

🐛 Bug Report

On our site we have a couple of duplicate doc pages. To avoid repeating content we have one doc as the source of truth then import the content like so:

import Content from './doc1.md';

<Content />

The issue is, the table of contents is not picked up on the pages that import the content. Please let me know if there is a better way to handle duplicate pages and if this usage is just conceptually wrong

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

npx @docusaurus/init@latest init my-website classic

in doc2:

import Content from './doc1.md';

<Content />

It's worth noting that this also happens on my 6 month old version, so I don't think that it's due to anything recent

[slorber]

This usage should be supported, but it's a current limitation of the existing system.

Unfortunately, I'm not sure how to implement this technically, and still busy on i18n.

In the meantime I'd recommend to only put raw text in mdx and duplicate the headings. That's not ideal but I don't have any other solution for now 😓

You could also add a build script that copy a file to multiple locations, or use a remark plugin that substitute a placeholder with a content string in multiple docs

[oriooctopus]

How difficult would it be to fix? I could possibly put up a PR

[slorber]

@oriooctopus unfortunately I suspect this to be quite complex to implement, and can't even give you much help to do so because I'm not sure how this should be done.

You can look at the code in this folder: packages/docusaurus-mdx-loader/src/remark/toc
If you are comfortable with ASTs and visitors you can give it a try

[jknoxville]

@slorber I think we can address this by getting docusaurus-mdx-loader to follow jsx tags into their imported sources when traversing the AST.

I did something similar to this before, using the fs api to read the file and getting remark to parse this in-place of the jsx node (so you can continue to recurse into the imported file and visit its nodes).

The only downside in my eyes is that we'd be using the node fs api, which means this package wouldn't work at runtime in the browser anymore (if it does now).

Do you think this would be an acceptable change?

[slorber]

Yes @jknoxville this is what I have in mind: a recursive visitor that is able to "flatten" the TOC structure of multiple MDX docs (and preserve the correct TOC ordering).

This code already runs in node (it's a Webpack loader)

[oriooctopus]

@jknoxville do you still have any interest in fixing this? If not, maybe we could sync on what you had in mind and I might be able to implement it?

[jknoxville]

@oriooctopus I'm interested, but it's not top of my queue right now, so feel free to take a stab!

Here's a prototype I made a while ago, for a remark plugin that effectively re-implements mdx transclusions by parsing the target of any imported markdown files, and then replacing any JSX nodes that use it, with the nodes of the target AST.
https://gist.github.com/jknoxville/8ed4cb8bcef348362a99dd70bb8006ae

It's scrappy, and not production-ready (currently uses eval for one thing - I'd recommend using babel to parse the imports instead), but it works. Maybe there's a more elegant way to do it.

What I imagine, is modifying search.js to do what that prototype does before it starts visiting headings to assemble its TOC.

I haven't tried this, but don't see why it wouldn't work.

[slorber]

if that helps I remembered that Gatsby has a way to extract all imports/exports from MDX.

https://github.com/gatsbyjs/gatsby/blob/2e42197025e2e1bac06c721c3cc44135bf8ef526/packages/gatsby-plugin-mdx/utils/gen-mdx.js#L199

[Laptopmini]

Can the table of content be overwritten using a React component?

I'm experiencing a similar issue where content generated via a React component is not parsed by the table of contents (for obvious reasons), which got me thinking about if there was a way to provide a custom table of content for certain pages which could help workaround this issue.

[slorber]

@Laptopmini, I think extracting headings from React components is an edge case, more complicated and expensive (as it would require rendering the comp to see what's the output), so it's not likely the first thing we could build.

We could allow you to export a custom toc in the MDX document, or modify the default one we computed for you?

---
id: myDoc
--- 

export function toc(originalToc) {
  return [...originalToc,{value: 'My React heading',id: 'my react anchor id',children: []}]
}

# Title

## Subtitle

Lorem Ipsum

Does it look like a good workaround for your usecase?