rehype-mdx-toc 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 boning-w
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# rehype-mdx-toc
+
+[![github actions](https://github.com/boning-w/rehype-mdx-toc/actions/workflows/ci.yml/badge.svg)](https://github.com/boning-w/rehype-mdx-toc/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/github/boning-w/rehype-mdx-toc/graph/badge.svg?token=5GBJECAL34)](https://codecov.io/github/boning-w/rehype-mdx-toc)
+[![license](https://img.shields.io/github/license/boning-w/rehype-mdx-toc)](https://github.com/boning-w/rehype-mdx-toc/blob/main/LICENSE)
+
+A rehype plugin to create the table of contents and convert it into MDX exports.
+
+## Table of Contents
+
+- [What is this?](#what-is-this)
+- [When should I use this?](#when-should-i-use-this)
+- [Install](#install)
+- [Usage](#usage)
+  - [✅ For `@mdx-js/mdx`](#-for-mdx-jsmdx)
+  - [✅ For `mdx-bundler`](#-for-mdx-bundler)
+  - [🚫 For `next-mdx-remote`](#-for-next-mdx-remote)
+- [API](#api)
+  - [Options](#options)
+- [Types](#types)
+- [License](#license)
+
+## What is this?
+
+This package is a [unified](https://unifiedjs.com/) ([rehype](https://rehypejs.github.io/rehype/)) plugin that generates a table of contents (TOC) from headings in your MDX files and converts it into MDX exports.
+
+## When should I use this?
+
+This plugin is useful when you want a table of contents data that is exported from MDX modules, which can then be used everwhere in your application.
+
+## Install
+
+You can install this package using npm:
+
+```shell
+npm install rehype-mdx-toc
+```
+
+## Usage
+
+Say we have mdx contents like this:
+
+```mdx
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+```
+
+...and our module `example.js` contains:
+
+```js
+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);
+```
+
+...then running `node example.js` will output:
+
+```json
+[
+  {
+    "depth": 1,
+    "value": "Heading 1",
+    "numbering": [1, 0, 0, 0, 0, 0],
+    "id": undefined,
+    "href": undefined
+  },
+  {
+    "depth": 2,
+    "value": "Heading 2",
+    "numbering": [1, 1, 0, 0, 0, 0],
+    "id": undefined,
+    "href": undefined
+  },
+  {
+    "depth": 3,
+    "value": "Heading 3",
+    "numbering": [1, 1, 1, 0, 0, 0],
+    "id": undefined,
+    "href": undefined
+  }
+]
+```
+
+### Use with `rehype-slug`
+
+To generate `id` and `href` properties for each TOC item, you can use the `rehype-slug` plugin before `rehype-mdx-toc`. This will automatically add `id` attributes to headings based on their text content.
+
+```js
+import { compile, run } from "@mdx-js/mdx";
+import rehypeSlug from "rehype-slug";
+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: [rehypeSlug, rehypeMdxToc],
+});
+const result = await run(compiled, { ...runtime });
+const toc = result.toc;
+console.log(toc);
+```
+
+This will output:
+
+```json
+[
+  {
+    "depth": 1,
+    "value": "Heading 1",
+    "numbering": [1, 0, 0, 0, 0, 0],
+    "id": "heading-1",
+    "href": "#heading-1"
+  },
+  {
+    "depth": 2,
+    "value": "Heading 2",
+    "numbering": [1, 1, 0, 0, 0, 0],
+    "id": "heading-2",
+    "href": "#heading-2"
+  },
+  {
+    "depth": 3,
+    "value": "Heading 3",
+    "numbering": [1, 1, 1, 0, 0, 0],
+    "id": "heading-3",
+    "href": "#heading-3"
+  }
+]
+```
+
+### ✅ For `@mdx-js/mdx`
+
+See [Usage](#usage) and [Use with rehype-slug](#use-with-rehype-slug) sections above.
+
+### ✅ For `mdx-bundler`
+
+For `mdx-bundler`, you can add this plugin to `bundleMDX()`'s mdxOptions:
+
+```js
+bundleMDX({
+  source: mdxSource,
+  mdxOptions(options, frontmatter) {
+    options.rehypePlugins = [...(options.rehypePlugins ?? []), rehypeMdxToc];
+    return options;
+  },
+});
+```
+
+> See [mdx-bundler#Accessing named exports](https://github.com/kentcdodds/mdx-bundler?tab=readme-ov-file#accessing-named-exports)
+> 
+> To access the `toc` export, You can use `getMDXExport` instead of `getMDXComponent` to treat the mdx file as a module instead of just a component.
+
+```js
+import { getMDXExport } from "mdx-bundler/client";
+
+function MDXPage({ code }: { code: string }) {
+  const mdxExport = getMDXExport(code);
+  console.log(mdxExport.toc); // 👈 get toc export here
+
+  const Component = React.useMemo(() => mdxExport.default, [code]);
+
+  return <Component />;
+}
+```
+
+### 🚫 For `next-mdx-remote`
+
+This plugin is not compatible with `next-mdx-remote` because `next-mdx-remote` does not support `import` and `export` statements in MDX files.
+
+See [import/export caveats of next-mdx-remote](https://github.com/hashicorp/next-mdx-remote?tab=readme-ov-file#import--export)
+
+> `import` and `export` statements cannot be used inside an MDX file.
+>
+> ...As for exports, the MDX content is treated as data, not a module, so there is no way for us to access any value which may be exported from the MDX passed to `next-mdx-remote`.
+
+## API
+
+The default export is the rehype plugin function.
+
+### Options
+
+- `default`: The default value to export if no headings. (Default: undefined).
+- `name`: The name of the export. (Default: "toc").
+- `skipDepth`: An array of heading depths to skip. If specified, headings of these depths will not be included in the TOC. (Default: `[]`).
+
+## Types
+
+This package is fully typed with [TypeScript](https://www.typescriptlang.org/). The plugin exports the types `HeadingDepth`, `RehypeMdxTocOptions`, `TocItem`.
+
+Mostly, you only need the `TocItem` type in your project:
+
+```ts
+export type TocItem = {
+  depth: HeadingDepth; // The level of the heading (1 for `<h1>`, 2 for `<h2>`, etc.).
+  value: string; // The text content of the heading.
+  numbering: number[]; //  An array representing the hierarchical numbering of the heading.
+  id?: string; // The ID of the heading, if available.
+  href?: string; // The link to the heading.
+  data?: Record<string, unknown>;
+};
+```
+
+## License
+
+[MIT](https://github.com/boning-w/rehype-mdx-toc/blob/main/LICENSE)

package/dist/src/index.d.ts

@@ -0,0 +1,76 @@
+import type { Root } from "hast";
+import type { VFile } from "vfile";
+/**
+ * Type representing the depth of headings in a table of contents.
+ * This is used to specify which heading levels (h1, h2, etc.) should be included
+ * in the table of contents.
+ *
+ * The values correspond to HTML heading elements:
+ * - 1 for `<h1>`
+ * - 2 for `<h2>`
+ * - 3 for `<h3>`
+ * - 4 for `<h4>`
+ * - 5 for `<h5>`
+ * - 6 for `<h6>`
+ */
+export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Options for the rehype-mdx-toc plugin.
+ *
+ * This type defines the configuration options that can be passed to the plugin.
+ * - `default`: Optional default value for the table of contents when no headings are found.
+ * - `name`: The name of the export variable for the table of contents.
+ */
+export type RehypeMdxTocOptions = {
+    /**
+     * Optional default value for the table of contents.
+     * If provided, this will be used when no headings are found.
+     *
+     * @default undefined
+     */
+    default?: unknown;
+    /**
+     * The name of the export variable for the table of contents.
+     *
+     * @default "toc"
+     */
+    name?: string;
+    /**
+     * An array of heading depths to skip.
+     * If specified, headings of these depths will not be included in the TOC.
+     *
+     * @default []
+     */
+    skipDepth?: HeadingDepth[];
+};
+/**
+ * Represents a single item in the table of contents (TOC).
+ *
+ * Each item corresponds to a heading in the MDX file and includes:
+ * - `depth`: The level of the heading (1 for `<h1>`, 2 for `<h2>`, etc.).
+ * - `value`: The text content of the heading.
+ * - `numbering`: An array representing the hierarchical numbering of the heading.
+ * - `id`: The ID of the heading, if available.
+ * - `href`: The link to the heading, typically a fragment identifier.
+ * - `data`: Additional data associated with the heading.
+ */
+export type TocItem = {
+    depth: HeadingDepth;
+    value: string;
+    numbering: number[];
+    id?: string;
+    href?: string;
+    data?: Record<string, unknown>;
+};
+/**
+ * Rehype plugin to generate a table of contents (TOC) for MDX files.
+ *
+ * This plugin processes the HAST tree to find all headings and constructs a TOC
+ * with hierarchical numbering. The TOC is then exported as a variable that can
+ * be used in the MDX module.
+ *
+ * @param options - Optional configuration for the plugin.
+ * @returns A function that transforms the HAST tree.
+ */
+export default function rehypeMdxToc({ name, ...options }?: RehypeMdxTocOptions): (tree: Root, file: VFile) => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAOnC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,EACnC,IAAY,EACZ,GAAG,OAAO,EACX,GAAE,mBAAwB,IAEjB,MAAM,IAAI,EAAE,MAAM,KAAK,UA8ChC"}

package/dist/src/index.js

@@ -0,0 +1,58 @@
+import { define } from "unist-util-mdx-define";
+import { headingRank } from "hast-util-heading-rank";
+import { toString } from "hast-util-to-string";
+import { valueToEstree } from "estree-util-value-to-estree";
+import { CONTINUE, visit } from "unist-util-visit";
+/**
+ * Rehype plugin to generate a table of contents (TOC) for MDX files.
+ *
+ * This plugin processes the HAST tree to find all headings and constructs a TOC
+ * with hierarchical numbering. The TOC is then exported as a variable that can
+ * be used in the MDX module.
+ *
+ * @param options - Optional configuration for the plugin.
+ * @returns A function that transforms the HAST tree.
+ */
+export default function rehypeMdxToc({ name = "toc", ...options } = {}) {
+    // Return the actual transformer function for rehype.
+    return (tree, file) => {
+        // This will hold the final table of contents data.
+        const toc = [];
+        // Tracks the current numbering for headings.
+        // Each index corresponds to a heading level: [h1, h2, h3, h4, h5, h6].
+        const currentNumbering = [0, 0, 0, 0, 0, 0];
+        // Visit every HTML element in the tree.
+        visit(tree, "element", function (node) {
+            // Check if this element is a heading (<h1>–<h6>).
+            const rank = headingRank(node);
+            // If the rank is undefined, skip this node.
+            if (rank === undefined)
+                return CONTINUE;
+            // If the depth is in the skipDepth array, skip this node.
+            const depth = rank;
+            if (options.skipDepth?.includes(depth))
+                return CONTINUE;
+            // Increment the counter for this heading level.
+            currentNumbering[depth - 1] += 1;
+            // Reset all deeper levels to zero.
+            // This ensures the numbering doesn't accidentally carry over.
+            for (let i = depth; i < currentNumbering.length; i++) {
+                currentNumbering[i] = 0;
+            }
+            // Add this heading to the TOC array.
+            toc.push({
+                depth,
+                value: toString(node),
+                numbering: [...currentNumbering],
+                id: node.properties?.id,
+                href: node.properties?.id ? `#${node.properties.id}` : undefined,
+            });
+        });
+        // Attach the TOC as an exported variable in the MDX file.
+        const data = toc.length ? toc : options.default;
+        define(tree, file, {
+            [name]: valueToEstree(data),
+        });
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAqEnD;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,EACnC,IAAI,GAAG,KAAK,EACZ,GAAG,OAAO,KACa,EAAE;IACzB,qDAAqD;IACrD,OAAO,CAAC,IAAU,EAAE,IAAW,EAAE,EAAE;QACjC,mDAAmD;QACnD,MAAM,GAAG,GAAc,EAAE,CAAC;QAE1B,6CAA6C;QAC7C,uEAAuE;QACvE,MAAM,gBAAgB,GAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAEtD,wCAAwC;QACxC,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,IAAI;YACnC,kDAAkD;YAClD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;YAE/B,4CAA4C;YAC5C,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,QAAQ,CAAC;YAExC,0DAA0D;YAC1D,MAAM,KAAK,GAAG,IAAoB,CAAC;YACnC,IAAI,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC;gBAAE,OAAO,QAAQ,CAAC;YAExD,gDAAgD;YAChD,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YAEjC,mCAAmC;YACnC,8DAA8D;YAC9D,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrD,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;YAED,qCAAqC;YACrC,GAAG,CAAC,IAAI,CAAC;gBACP,KAAK;gBACL,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC;gBACrB,SAAS,EAAE,CAAC,GAAG,gBAAgB,CAAC;gBAChC,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,EAAwB;gBAC7C,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS;aACjE,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,0DAA0D;QAC1D,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAEhD,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE;YACjB,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/test/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/test/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../test/index.ts"],"names":[],"mappings":""}

package/dist/test/index.js

@@ -0,0 +1,250 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { compile, run } from "@mdx-js/mdx";
+import rehypeMdxToc, {} from "rehype-mdx-toc";
+import rehypeSlug from "rehype-slug";
+import * as runtime from "react/jsx-runtime";
+const source = `
+  # The Main Heading
+
+  ## Section _1_
+
+  ### Subheading
+
+  ### Mubheading
+
+  ## Section _2_
+
+  ### \`Subheading\`
+
+  ### [Mubheading](#)
+
+  > #### QuoteHeading
+  > Some Content
+  > #### **QuoteHeading**
+  > Some Content
+
+  + ##### **ListItem** _Heading_
+  + ##### _ListItem_ **Heading**
+`;
+async function getTocFromMdxModule(mdxContent) {
+    const compiled = await compile(mdxContent, {
+        outputFormat: "function-body",
+        rehypePlugins: [rehypeMdxToc],
+    });
+    const result = await run(compiled, { ...runtime });
+    const toc = result.toc;
+    return toc;
+}
+async function getTocFromMdxModuleWithRehypeSlug(mdxContent) {
+    const compiled = await compile(mdxContent, {
+        outputFormat: "function-body",
+        rehypePlugins: [rehypeSlug, rehypeMdxToc],
+    });
+    const result = await run(compiled, { ...runtime });
+    const toc = result.toc;
+    return toc;
+}
+describe("rehype-mdx-toc", () => {
+    it("should export toc to MDX module", async () => {
+        const mdx = "# Heading 1";
+        const toc = await getTocFromMdxModule(mdx);
+        assert.ok(Array.isArray(toc), "Should export toc");
+    });
+    it("should generate undefined TOC for no headings", async () => {
+        const mdx = "This is a test without headings.";
+        const toc = await getTocFromMdxModule(mdx);
+        assert.ok(toc === undefined, "Should generate undefined TOC for no headings");
+    });
+    it("should generate correct TOC structure without heading IDs", async () => {
+        const toc = await getTocFromMdxModule("# Heading 1\n\n## Heading 2\n\n### Heading 3");
+        assert.deepEqual(toc, [
+            {
+                depth: 1,
+                value: "Heading 1",
+                numbering: [1, 0, 0, 0, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+            {
+                depth: 2,
+                value: "Heading 2",
+                numbering: [1, 1, 0, 0, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+            {
+                depth: 3,
+                value: "Heading 3",
+                numbering: [1, 1, 1, 0, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+        ]);
+    });
+    it("should generate correct TOC structure with heading IDs", async () => {
+        const toc = await getTocFromMdxModuleWithRehypeSlug(source);
+        assert.deepEqual(toc, [
+            {
+                depth: 1,
+                value: "The Main Heading",
+                numbering: [1, 0, 0, 0, 0, 0],
+                id: "the-main-heading",
+                href: "#the-main-heading",
+            },
+            {
+                depth: 2,
+                value: "Section 1",
+                numbering: [1, 1, 0, 0, 0, 0],
+                id: "section-1",
+                href: "#section-1",
+            },
+            {
+                depth: 3,
+                value: "Subheading",
+                numbering: [1, 1, 1, 0, 0, 0],
+                id: "subheading",
+                href: "#subheading",
+            },
+            {
+                depth: 3,
+                value: "Mubheading",
+                numbering: [1, 1, 2, 0, 0, 0],
+                id: "mubheading",
+                href: "#mubheading",
+            },
+            {
+                depth: 2,
+                value: "Section 2",
+                numbering: [1, 2, 0, 0, 0, 0],
+                id: "section-2",
+                href: "#section-2",
+            },
+            {
+                depth: 3,
+                value: "Subheading",
+                numbering: [1, 2, 1, 0, 0, 0],
+                id: "subheading-1",
+                href: "#subheading-1",
+            },
+            {
+                depth: 3,
+                value: "Mubheading",
+                numbering: [1, 2, 2, 0, 0, 0],
+                id: "mubheading-1",
+                href: "#mubheading-1",
+            },
+            {
+                depth: 4,
+                value: "QuoteHeading",
+                numbering: [1, 2, 2, 1, 0, 0],
+                id: "quoteheading",
+                href: "#quoteheading",
+            },
+            {
+                depth: 4,
+                value: "QuoteHeading",
+                numbering: [1, 2, 2, 2, 0, 0],
+                id: "quoteheading-1",
+                href: "#quoteheading-1",
+            },
+            {
+                depth: 5,
+                value: "ListItem Heading",
+                numbering: [1, 2, 2, 2, 1, 0],
+                id: "listitem-heading",
+                href: "#listitem-heading",
+            },
+            {
+                depth: 5,
+                value: "ListItem Heading",
+                numbering: [1, 2, 2, 2, 2, 0],
+                id: "listitem-heading-1",
+                href: "#listitem-heading-1",
+            },
+        ]);
+    });
+    it("should export toc with default export name", async () => {
+        const toc = await getTocFromMdxModule(source);
+        assert.ok(Array.isArray(toc), "should export toc with default export name");
+    });
+    it("should export toc with custom export name", async () => {
+        const compiled = await compile(source, {
+            outputFormat: "function-body",
+            rehypePlugins: [[rehypeMdxToc, { name: "customToc" }]],
+        });
+        const result = await run(compiled, { ...runtime });
+        assert.ok(Array.isArray(result.customToc), "Should export toc with custom name");
+    });
+    it("should export toc with default value (which is undefined) without headings", async () => {
+        const mdx = "This is a test without headings.";
+        const toc = await getTocFromMdxModule(mdx);
+        assert.ok(toc === undefined, "should export toc with default value (which is undefined) without headings");
+    });
+    it("should export toc with custom default value without headings", async () => {
+        const mdx = "This is a test without headings.";
+        const compiled = await compile(mdx, {
+            outputFormat: "function-body",
+            rehypePlugins: [[rehypeMdxToc, { default: "No headings in this MDX" }]],
+        });
+        const result = await run(compiled, { ...runtime });
+        assert.ok((result.toc = "No headings in this MDX"), "should export toc with custom default value without headings");
+    });
+    it("should skip headings based on skipDepth option", async () => {
+        const mdx = `
+      # Heading 1
+      ## Heading 2
+      ### Heading 3
+      #### Heading 4
+      #### Heading 4.1
+      ##### Heading 5
+      ###### Heading 6
+      ### Heading 3.1
+      #### Heading 4.2
+    `;
+        const compiled = await compile(mdx, {
+            outputFormat: "function-body",
+            rehypePlugins: [[rehypeMdxToc, { skipDepth: [1, 2, 5, 6] }]],
+        });
+        const result = await run(compiled, { ...runtime });
+        const toc = result.toc;
+        assert.deepEqual(toc, [
+            {
+                depth: 3,
+                value: "Heading 3",
+                numbering: [0, 0, 1, 0, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+            {
+                depth: 4,
+                value: "Heading 4",
+                numbering: [0, 0, 1, 1, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+            {
+                depth: 4,
+                value: "Heading 4.1",
+                numbering: [0, 0, 1, 2, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+            {
+                depth: 3,
+                value: "Heading 3.1",
+                numbering: [0, 0, 2, 0, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+            {
+                depth: 4,
+                value: "Heading 4.2",
+                numbering: [0, 0, 2, 1, 0, 0],
+                id: undefined,
+                href: undefined,
+            },
+        ]);
+    });
+});
+//# sourceMappingURL=index.js.map

package/dist/test/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../test/index.ts"],"names":[],"mappings":"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"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/index.ts","../test/index.ts"],"version":"5.8.3"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "rehype-mdx-toc",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "A rehype plugin to create the table of contents and convert it into MDX exports",
+  "keywords": [
+    "toc",
+    "table of contents",
+    "markdown",
+    "markdown-toc",
+    "mdx",
+    "rehype",
+    "rehype-plugin",
+    "hast",
+    "unified"
+  ],
+  "homepage": "https://github.com/boning-w/rehype-mdx-toc#readme",
+  "bugs": {
+    "url": "https://github.com/boning-w/rehype-mdx-toc/issues"
+  },
+  "license": "MIT",
+  "author": "boning <wang.boning@outlook.com>",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "types": "./dist/src/index.d.ts",
+  "main": "./dist/src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boning-w/rehype-mdx-toc.git"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "test-coverage": "c8 --100 node --test && c8 report --reporter=html --reporter=lcov"
+  },
+  "dependencies": {
+    "estree-util-value-to-estree": "^3.4.0",
+    "hast-util-heading-rank": "^3.0.0",
+    "hast-util-to-string": "^3.0.1",
+    "unist-util-mdx-define": "^1.1.2",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@mdx-js/mdx": "^3.1.0",
+    "@types/hast": "^3.0.4",
+    "@types/node": "^22.16.0",
+    "@types/react": "^19.1.8",
+    "@types/vfile": "^3.0.2",
+    "c8": "^10.1.3",
+    "react": "^19.1.0",
+    "rehype-slug": "^6.0.0",
+    "typescript": "^5.8.3"
+  },
+  "sideEffects": false
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+import type { Root } from "hast";
+import type { VFile } from "vfile";
+import { define } from "unist-util-mdx-define";
+import { headingRank } from "hast-util-heading-rank";
+import { toString } from "hast-util-to-string";
+import { valueToEstree } from "estree-util-value-to-estree";
+import { CONTINUE, visit } from "unist-util-visit";
+
+/**
+ * Type representing the depth of headings in a table of contents.
+ * This is used to specify which heading levels (h1, h2, etc.) should be included
+ * in the table of contents.
+ *
+ * The values correspond to HTML heading elements:
+ * - 1 for `<h1>`
+ * - 2 for `<h2>`
+ * - 3 for `<h3>`
+ * - 4 for `<h4>`
+ * - 5 for `<h5>`
+ * - 6 for `<h6>`
+ */
+export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * Options for the rehype-mdx-toc plugin.
+ *
+ * This type defines the configuration options that can be passed to the plugin.
+ * - `default`: Optional default value for the table of contents when no headings are found.
+ * - `name`: The name of the export variable for the table of contents.
+ */
+export type RehypeMdxTocOptions = {
+  /**
+   * Optional default value for the table of contents.
+   * If provided, this will be used when no headings are found.
+   *
+   * @default undefined
+   */
+  default?: unknown;
+
+  /**
+   * The name of the export variable for the table of contents.
+   *
+   * @default "toc"
+   */
+  name?: string;
+
+  /**
+   * An array of heading depths to skip.
+   * If specified, headings of these depths will not be included in the TOC.
+   *
+   * @default []
+   */
+  skipDepth?: HeadingDepth[];
+};
+
+/**
+ * Represents a single item in the table of contents (TOC).
+ *
+ * Each item corresponds to a heading in the MDX file and includes:
+ * - `depth`: The level of the heading (1 for `<h1>`, 2 for `<h2>`, etc.).
+ * - `value`: The text content of the heading.
+ * - `numbering`: An array representing the hierarchical numbering of the heading.
+ * - `id`: The ID of the heading, if available.
+ * - `href`: The link to the heading, typically a fragment identifier.
+ * - `data`: Additional data associated with the heading.
+ */
+export type TocItem = {
+  depth: HeadingDepth;
+  value: string;
+  numbering: number[];
+  id?: string;
+  href?: string;
+  data?: Record<string, unknown>;
+};
+
+/**
+ * Rehype plugin to generate a table of contents (TOC) for MDX files.
+ *
+ * This plugin processes the HAST tree to find all headings and constructs a TOC
+ * with hierarchical numbering. The TOC is then exported as a variable that can
+ * be used in the MDX module.
+ *
+ * @param options - Optional configuration for the plugin.
+ * @returns A function that transforms the HAST tree.
+ */
+export default function rehypeMdxToc({
+  name = "toc",
+  ...options
+}: RehypeMdxTocOptions = {}) {
+  // Return the actual transformer function for rehype.
+  return (tree: Root, file: VFile) => {
+    // This will hold the final table of contents data.
+    const toc: TocItem[] = [];
+
+    // Tracks the current numbering for headings.
+    // Each index corresponds to a heading level: [h1, h2, h3, h4, h5, h6].
+    const currentNumbering: number[] = [0, 0, 0, 0, 0, 0];
+
+    // Visit every HTML element in the tree.
+    visit(tree, "element", function (node) {
+      // Check if this element is a heading (<h1>–<h6>).
+      const rank = headingRank(node);
+
+      // If the rank is undefined, skip this node.
+      if (rank === undefined) return CONTINUE;
+
+      // If the depth is in the skipDepth array, skip this node.
+      const depth = rank as HeadingDepth;
+      if (options.skipDepth?.includes(depth)) return CONTINUE;
+
+      // Increment the counter for this heading level.
+      currentNumbering[depth - 1] += 1;
+
+      // Reset all deeper levels to zero.
+      // This ensures the numbering doesn't accidentally carry over.
+      for (let i = depth; i < currentNumbering.length; i++) {
+        currentNumbering[i] = 0;
+      }
+
+      // Add this heading to the TOC array.
+      toc.push({
+        depth,
+        value: toString(node),
+        numbering: [...currentNumbering],
+        id: node.properties?.id as string | undefined,
+        href: node.properties?.id ? `#${node.properties.id}` : undefined,
+      });
+    });
+
+    // Attach the TOC as an exported variable in the MDX file.
+    const data = toc.length ? toc : options.default;
+    
+    define(tree, file, {
+      [name]: valueToEstree(data),
+    });
+  };
+}