Add rehype-mdx-toc to export toc into MDX module

[boning-w]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything or linked relevant results below
• I made sure the docs are up to date
• I included tests (or that’s not needed)

Description of changes

I wrote a rehype plugin rehype-mdx-toc that allows users to export the table of contents (TOC) data as a named export from an MDX module.

Why another table of contents plugin?

Since MDX supports exporting data from MDX modules, it's much more convinent to export the TOC — so that users can use it whatever they like, just like with remark-mdx-frontmatter.

Simple usage:

import { compile, run } from "@mdx-js/mdx";
import rehypeMdxToc from "rehype-mdx-toc";
import * as runtime from "react/jsx-runtime";

const mdxContent = `
# Heading 1
## Heading 2
### Heading 3
`;

const compiled = await compile(mdxContent, {
  outputFormat: "function-body",
  rehypePlugins: [rehypeMdxToc],
});
const result = await run(compiled, { ...runtime });
const toc = result.toc;
console.log(toc);

With some bundlers — like @mdx-js/esbuild, @mdx-js/rollup, and @mdx-js/loader, we can easily import the TOC data at build time:

import MDXContent, { toc } from "./you-mdx-file.mdx";

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (9bc5528) to head (d28659c).
Report is 26 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #203   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            6         6           
  Lines          154       163    +9     
=========================================
+ Hits           154       163    +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ChristianMurphy]

Thanks for sharing @boning-w!

Some suggestions:

• Consider widening dependencies to x.0.0 to allow npm (and packageme manager friends) to de-duplicate the dependencies as much as possible https://github.com/boning-w/rehype-mdx-toc/blob/f1cc7f1ad5a8573bfcd87ca82fc2133f5c6f17a6/package.json#L47-L51
• What is the intent of default the option? Could it be made more specific than unknown? https://github.com/boning-w/rehype-mdx-toc/blob/f1cc7f1ad5a8573bfcd87ca82fc2133f5c6f17a6/src/index.ts#L38
• It is recommended to have a lint checker, whether that be prettier, xo, standard, or a custom ESLint config https://github.com/boning-w/rehype-mdx-toc/blob/f1cc7f1ad5a8573bfcd87ca82fc2133f5c6f17a6/package.json#L43
• These options should not be needed in nodenext module mode https://github.com/boning-w/rehype-mdx-toc/blob/f1cc7f1ad5a8573bfcd87ca82fc2133f5c6f17a6/tsconfig.json#L23-L24
• avoid skipping libcheck, it can hide upstream issues that may impact your users https://github.com/boning-w/rehype-mdx-toc/blob/f1cc7f1ad5a8573bfcd87ca82fc2133f5c6f17a6/tsconfig.json#L38

[boning-w]

Hi @ChristianMurphy, I really appreciate for your code review.

• I have updated the dependencies versions to 'x.0.0'.
• I added Biome as a lint checker, and added it in the test script:
  "test": "npx @biomejs/biome check ./src ./test && node --test".
• I removed the unnecessary options from tsconfig.json and also remove skipLibCheck.

Regarding:

• What is the intent of default the option? Could it be made more specific than unknown? https://github.com/boning-w/rehype-mdx-toc/blob/f1cc7f1ad5a8573bfcd87ca82fc2133f5c6f17a6/src/index.ts#L38

The default option is to provide a fallback value for users when there are no headings in Markdown contents. By default. it is undefine, but maybe users want to configure their own default value when no headings are found. Since the value could be undefine, [] or others, I use the type unknown.

I commited these changes and published a new version v1.1.0 to npm.

Here is the new version.

[remcohaszing]

Thanks! Your plugin looks really cool!

I just don’t think this is the right place to list it. None of the MDX specific plugins are listed in the rehype or remark plugin lists. A better place would be https://mdxjs.com/docs/extending-mdx/#list-of-plugins.

[boning-w]

Got it! I may create a pull request there. Should I cloes this pull request?

[remcohaszing]

Let’s have another maintainer close it if they agree with me. :)

[JounQin]

I agree it should be listed as a mdx specified plugin instead.

[wooorm]

I’ll close this here. Yes, please do add it there! Thanks everyone!