heading slugs/ids in nested mdx

[artola]

I have foo.mdx that imports bar.mdx, my output is kinda ok, but the plugins are working in isolation for each file, and they do not share any context (or I could not find a way to do it).
For example, just using rehype-slug. The idea is to add an id to the headings and it does it, just that also repeating the same "id" in place of adding a trailing number to differentiate them.

<!-- foo.mdx -->

## XXX

import Bar from './bar.mdx';

<Bar />

<!-- bar.mdx -->

## XXX

The output contains 2 headers with exactly the same id (xxx), in place of xxx-1 and xxx-2 as if both were in the same file.

As far as I did debug, the compilation treats the files as different tree not connected.

In my case, I wrote a plugin to collect the headings, all of them, and I can see the plugin running on each file and I do not see a way to group them (using NextJS, with the default config and rehype-slug).

Can someone give me a hint how to solve such situation? is there a way to share context in the loader that gets reset on every run?

[ChristianMurphy]

Welcome @artola! 👋
To understand why, it can be helpful to review the architecture of MDX.
https://mdxjs.com/packages/mdx/#architecture

Rehype plugins in the middle of the pipeline.
And only see a single file at a time.
imports are resolved at the very end after the JavaScript is generated, it gets run in a browser/server and follows that import.

It may be possible to create a slugger that uses file information to ensure the slugs are unique
https://unifiedjs.com/learn/

[artola]

Thanks @ChristianMurphy.
I did read the architecture as mentioned, by the way, the documentation says:

@mdx-js/mdx is a unified pipeline — wrapped so that most folks don’t need to know about unified: core.js#L65.

and such line states:

@Property {string | null | undefined} [pragma='React.createElement']

probably should point to:

mdx/packages/mdx/lib/core.js

Line 197 in ce4fef0

const pipeline = unified().use(remarkParse)

Would you accept a PR for docs? I am not looking for any credit, if it is easy for you, just please go ahead.

About the slugger problem with duplicate ids, it was just an example. I am collecting data and looking for the right moment to push it into the tree. If something solves the slugger case, probably can be used for my case too.

[ChristianMurphy]

is a unified pipeline — wrapped so that most folks don’t need to know about unified

In most cases it isn't needed.
In this particular case it's the crux of the issue.

Would you accept a PR for docs?

Sure, it looks like that got out of sync in a JSDoc update, a PR would be welcomed!

[artola]

@mdx-js/mdx is a unified pipeline — wrapped so that most folks don’t need to know about unified: core.js#L65.

About the broken link in the docs, I would suggest to avoid linking to the source code, as it is likely to be broken again. Even a permalink will become obsolete overtime.

`@mdx-js/mdx` is a unified pipeline — wrapped so that most folks don’t need to know about unified, but can easily integrate their remark and rehype plugins.

@ChristianMurphy Here the PR with above mentioned changes: #2508

[wooorm]

About the slugger problem with duplicate ids, it was just an example. I am collecting data and looking for the right moment to push it into the tree. If something solves the slugger case, probably can be used for my case too.

What is your root case?

The line of thinking I’d recommend going into, is the same as what GH is doing for footnotes in comments: they prefix IDs in each comment, with an ID unique to that comment. That way, a page can have multiple documents, and IDs are “scoped” to the subdocument.

[artola]

My case is somehow similar to rehype-toc, it is about collecting the headings, in place of injecting ToC in the document as a list, I use a mdx component to push data into the context.
It works well in the boundaries of all the headings are in the same file, or the first MDX is re-exporting a file (for example, export {default} from "some-other-file.mdx";).
Otherwise, if files are nested, as it happens with rehype-toc or rehype-slug, and due the nature of webpack loaders, I end up with with several components each of them pushing a partial of the headings.

import {headingRank} from 'hast-util-heading-rank';
import {toString} from 'hast-util-to-string';
import {fromMarkdown} from 'mdast-util-from-markdown';
import {mdxFromMarkdown} from 'mdast-util-mdx';
import {mdxjs} from 'micromark-extension-mdxjs';
import {visit} from 'unist-util-visit';

export default function rehypeOutline() {
  return (tree) => {
    const headings = [];

    visit(tree, 'element', function (node) {
      const rank = headingRank(node);

      if (rank) {
        headings.push({
          rank,
          id: node.properties.id.toString(),
          title: toString(node),
        });
      }
    });

    const doc = `<Outline headings={${JSON.stringify(headings)}} />`;

    const {
      children: [node],
    } = fromMarkdown(doc, {
      extensions: [mdxjs()],
      mdastExtensions: [mdxFromMarkdown()],
    });

    tree.children.push(node);
  };
}

[wooorm]

You have to understand that compilers/asts/plugins are ahead of time. So, on the “server”. Static analysis.
What is displayed eventually in headings is dynamic, “client side”.
A heading could contain ## {Math.random()}. A heading could conflict when it’s wrapped in one file, but not when wrapped in another file.

I’d recommend what I mentioned in my previous comment: scoping IDs per “document”.

[artola]

Right. There are some limits, like you mention ## {Math.random()} where even rehype-slug can not do it properly.
The problem that I try to solve:

• should I wait to the runtime and use React.Children to walk and get the headings/ids? (I have a function to do that too).
  It works, it is able to resolve the random number too, but rehype-slug fails with the random number and also with duplicated ids for nested components with same text.

  composed.mdx:

  import Example1 from './example1.mdx';
  import Example2 from './example2.mdx';
  
  <Example1 />
  <Example2 />

  example1.mdx:

  # Example
  Foo

  example2.mdx:

  # Example
  Bar

• should I extract the headings at build time (cheap with rehype plugin, no React static render)? (the shown plugin above)
  It does a pretty good job at build time, with no runtime cost. It fails to find the random number and it does not support the above composition.

I’d recommend what I mentioned in my previous comment: scoping IDs per “document”.
In rehype-slug the scope is per file, how do you detect a change of "document" in the plugin ?

[wooorm]

but rehype-slug fails with the random number and also with duplicated ids for nested components with same text.

What is “fail”? I personally see it as trade offs that are not particularly better/worse.

I’d recommend what I mentioned in my previous comment: scoping IDs per “document”.

In rehype-slug the scope is per file, how do you detect a change of "document" in the plugin ?

With another plugin. A plugin that generates an ID for the file. And then prepends it before all IDs in the document.