rehype-custom-toc 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 roboin
+
+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,122 @@
+# rehype-custom-toc
+
+rehype plugin to generate a customizable table of contents.
+
+## Installation
+
+```bash
+npm install rehype-custom-toc
+```
+
+## Example
+
+```javascript
+import remarkComment from "remark-comment";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import rehypeCustomToc from "./index";
+import rehypeStringify from "rehype-stringify";
+import { unified } from "unified";
+
+/**
+ * A comment node generated by the `remark-comment` plugin.
+ */
+interface Comment extends Node {
+    type: "comment";
+    value: "";
+    commentValue: string;
+}
+
+const processor = unified()
+    .use(remarkParse)
+    .use(remarkComment, {
+        ast: true
+    })
+    .use(remarkRehype, {
+        handlers: {
+            /**
+             * Convert a mdast comment node to a hast comment node.
+             * @param _ State
+             * @param node mdast comment node
+             * @returns hast comment node
+             */
+            comment: (_, node: Comment) => ({
+                type: "comment",
+                value: node.commentValue
+            })
+        }
+    })
+    .use(rehypeCustomToc)
+    .use(rehypeStringify);
+
+const markdown = `
+# Title
+
+This is a sample markdown paragraph.
+
+<!-- toc -->
+
+## Section 1
+
+### Subsection 1.1
+`;
+
+processor.process(markdown).then((result) => {
+    console.log(result.toString());
+});
+```
+
+The above code will output the following (formatted for readability):
+
+```html
+<h1 id="title">Title</h1>
+<p>This is a sample markdown paragraph.</p>
+<aside class="toc">
+    <h2>Contents</h2>
+    <nav>
+        <ul>
+            <li><a href="#title">Title</a></li>
+            <ul>
+                <li><a href="#section-1">Section 1</a></li>
+                <ul>
+                    <li><a href="#subsection-11">Subsection 1.1</a></li>
+                </ul>
+            </ul>
+        </ul>
+    </nav>
+</aside>
+<h2 id="section-1">Section 1</h2>
+<h3 id="subsection-11">Subsection 1.1</h3>
+```
+
+## Options
+
+### `template`
+
+A function that takes the generated HTML and returns the final HTML. This can be used to wrap the generated HTML in a custom template.
+
+Default:
+
+```javascript
+const defaultTemplate = (html) => {
+    return `
+<aside class="toc">
+    <h2>Contents</h2>
+    <nav>
+        ${html}
+    </nav>
+</aside>`.trim();
+};
+```
+
+### `maxDepth`
+
+The maximum depth of headings to include in the table of contents.
+
+Default: `3`
+
+### `ordered`
+
+Whether to use an ordered list (`<ol>`) or an unordered list (`<ul>`).
+
+Default: `false`

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import type { Root } from "hast";
+import type { Plugin } from "unified";
+/**
+ * Custom TOC template function.
+ * @param html HTML content of the TOC list
+ * @returns Wrapped HTML content
+ */
+type RehypeCustomTocTemplate = (html: string) => string;
+/**
+ * Options for the rehypeCustomToc plugin.
+ */
+interface RehypeCustomTocOptions {
+    /**
+     * A function that takes the generated HTML and returns the final HTML.
+     * This can be used to wrap the generated HTML in a custom template.
+     * @default
+     * ```javascript
+     * const defaultTemplate = (html) => {
+     *     return `
+     * <aside class="toc">
+     *     <h2>Contents</h2>
+     *     <nav>
+     *         ${html}
+     *     </nav>
+     * </aside>`.trim();
+     * };
+     * ```
+     */
+    template?: RehypeCustomTocTemplate;
+    /**
+     * The maximum depth of headings to include in the table of contents.
+     * @default 3
+     */
+    maxDepth?: number;
+    /**
+     * Whether to use an ordered list (`<ol>`) or an unordered list (`<ul>`).
+     * @default false
+     */
+    ordered?: boolean;
+}
+/**
+ * Rehype plugin to generate a table of contents.
+ * @param userOptions Options for the plugin
+ * @returns The plugin
+ */
+declare const rehypeCustomToc: Plugin<[RehypeCustomTocOptions], Root>;
+export default rehypeCustomToc;
+export type { RehypeCustomTocOptions, RehypeCustomTocTemplate };

package/dist/index.js

@@ -0,0 +1,141 @@
+import GitHubSlugger from "github-slugger";
+import { fromHtml } from "hast-util-from-html";
+import { h } from "hastscript";
+import { isNonEmptyArray } from "@robot-inventor/ts-utils";
+import { toHtml } from "hast-util-to-html";
+import { toText } from "hast-util-to-text";
+import { visit } from "unist-util-visit";
+import { visitParents } from "unist-util-visit-parents";
+/**
+ * Default TOC template function for {@link RehypeCustomTocTemplate}.
+ * @param html HTML content of the TOC list
+ * @returns Wrapped HTML content
+ */
+const defaultTemplate = (html) => `
+<aside class="toc">
+    <h2>Contents</h2>
+    <nav>
+        ${html}
+    </nav>
+</aside>`.trim();
+/**
+ * Default options for the rehypeCustomToc plugin.
+ */
+const DEFAULT_OPTIONS = {
+    maxDepth: 3,
+    ordered: false,
+    template: defaultTemplate
+};
+/**
+ * Generate the table of contents from the headings data.
+ * @param tree The HAST tree
+ * @param options Options for the plugin
+ * @returns The generated table of contents
+ */
+// eslint-disable-next-line max-statements, max-lines-per-function
+const generateToc = (tree, options) => {
+    const toc = {
+        children: [],
+        properties: {},
+        tagName: options.ordered ? "ol" : "ul",
+        type: "element"
+    };
+    const headings = [];
+    const slugger = new GitHubSlugger();
+    visit(tree, "element", (node) => {
+        if (!["h1", "h2", "h3", "h4", "h5", "h6"].includes(node.tagName))
+            return;
+        const text = toText(node).trim();
+        const slug = node.properties["id"] || slugger.slug(text);
+        node.properties["id"] = slug;
+        // eslint-disable-next-line no-magic-numbers
+        const depth = parseInt(node.tagName.slice(1), 10);
+        headings.push({
+            depth,
+            slug,
+            text
+        });
+    });
+    if (!isNonEmptyArray(headings))
+        return [];
+    let currentDepth = headings[0].depth;
+    let currentParent = toc;
+    const parents = [toc];
+    for (const heading of headings) {
+        // eslint-disable-next-line no-continue
+        if (heading.depth > options.maxDepth)
+            continue;
+        const li = h("li", h("a", { href: `#${heading.slug}` }, heading.text));
+        if (heading.depth === currentDepth) {
+            // The current heading is at the same level as the previous one.
+            currentParent.children.push(li);
+            currentDepth = heading.depth;
+        }
+        else if (heading.depth > currentDepth) {
+            // The current heading is at a deeper level than the previous one.
+            const ul = h(options.ordered ? "ol" : "ul", li);
+            currentParent.children.push(ul);
+            currentParent = ul;
+            parents.push(currentParent);
+            currentDepth = heading.depth;
+        }
+        else {
+            // The current heading is at a shallower level than the previous one.
+            // eslint-disable-next-line id-length
+            for (let i = 0; i < currentDepth - heading.depth; i++) {
+                parents.pop();
+                // eslint-disable-next-line no-magic-numbers
+                const parentNode = parents[parents.length - 1];
+                if (!parentNode) {
+                    throw new Error("Parent node not found. Make sure the headings are sorted by depth.");
+                }
+                currentParent = parentNode;
+            }
+            currentParent.children.push(li);
+            currentDepth = heading.depth;
+        }
+    }
+    return fromHtml(options.template(toHtml(toc)), { fragment: true }).children;
+};
+/**
+ * Rehype plugin to generate a table of contents.
+ * @param userOptions Options for the plugin
+ * @returns The plugin
+ */
+const rehypeCustomToc = (userOptions) => {
+    const options = { ...DEFAULT_OPTIONS, ...userOptions };
+    /**
+     * The transformer function for the plugin.
+     * @param tree The HAST tree
+     */
+    const transformer = (tree) => {
+        const tocNodes = generateToc(tree, options);
+        let tocInserted = false;
+        visitParents(tree, "comment", (node, ancestors) => {
+            if (node.value.trim().toLowerCase() !== "toc")
+                return;
+            // eslint-disable-next-line no-magic-numbers, @typescript-eslint/no-non-null-assertion
+            const parent = ancestors.at(-1);
+            const index = parent.children.indexOf(node);
+            // eslint-disable-next-line no-magic-numbers
+            if (parent.type === "element" && parent.tagName === "p" && parent.children.length === 1) {
+                // eslint-disable-next-line no-magic-numbers, @typescript-eslint/no-non-null-assertion
+                const grand = ancestors.at(-2);
+                const parentIdx = grand.children.indexOf(parent);
+                // eslint-disable-next-line no-magic-numbers
+                grand.children.splice(parentIdx, 1, ...tocNodes);
+            }
+            else {
+                // eslint-disable-next-line no-magic-numbers
+                parent.children.splice(index, 1, ...tocNodes);
+            }
+            tocInserted = true;
+        });
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!tocInserted) {
+            tree.children.unshift(...tocNodes);
+        }
+    };
+    return transformer;
+};
+export default rehypeCustomToc;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "rehype-custom-toc",
+  "version": "0.0.0",
+  "description": "rehype plugin to generate a customizable table of contents",
+  "keywords": [
+    "rehype",
+    "toc",
+    "unified",
+    "hast",
+    "html",
+    "markdown"
+  ],
+  "homepage": "https://github.com/Robot-Inventor/rehype-custom-toc#readme",
+  "bugs": {
+    "url": "https://github.com/Robot-Inventor/rehype-custom-toc/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Robot-Inventor/rehype-custom-toc.git"
+  },
+  "license": "MIT",
+  "author": "Robot-Inventor",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "cross-env NODE_ENV=\"production\" vitest",
+    "lint": "eslint --flag unstable_native_nodejs_ts_config \"./src/**/*.ts\"",
+    "build": "tsc",
+    "format": "prettier --write \"./src/**/*.ts\"",
+    "format:check": "prettier --check \"./src/**/*.ts\"",
+    "ci:version": "changeset version",
+    "ci:publish": "npm run build && changeset publish"
+  },
+  "dependencies": {
+    "@robot-inventor/ts-utils": "^0.8.3",
+    "github-slugger": "^2.0.0",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-to-html": "^9.0.5",
+    "hast-util-to-text": "^4.0.2",
+    "hastscript": "^9.0.1",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "unist-util-visit-parents": "^6.0.2"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@robot-inventor/eslint-config": "^11.1.1",
+    "@robot-inventor/tsconfig-base": "^7.0.0",
+    "@types/hast": "^3.0.4",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "rehype-stringify": "^10.0.1",
+    "remark-comment": "^1.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "overrides": {
+    "zod-validation-error": "^5.0.0"
+  }
+}