rehype-custom-toc 1.0.7 → 1.1.0

package/README.md

@@ -12,7 +12,7 @@ npm install rehype-custom-toc
 
 The table of contents will be inserted at the location of the `<!-- toc -->` comment or at the beginning of the file if no comment is found.
 
-When parsing HTML with rehype, the `<!-- toc -->` comment is preserved as-is, but when converting from Markdown you need to convert Markdown comments to HTML comments (as shown below with `remark-comment`) so rehype-custom-toc can detect the ToC marker.
+When parsing HTML with rehype, the `<!-- toc -->` comment is preserved as-is, but when converting from Markdown you need to convert Markdown comments to HTML comments (as shown below with `remark-comment`) so rehype-custom-toc can detect the TOC marker.
 
 ```typescript
 import remarkComment from "remark-comment";
@@ -93,6 +93,43 @@ The above code will output the following (formatted for readability):
 <h3 id="subsection-11">Subsection 1.1</h3>
 ```
 
+### Add IDs to headings without a TOC
+
+You can import `rehypeSlugger` from `rehype-custom-toc` and use it as a standalone plugin to add slugs to headings without generating a table of contents. This is useful if you want to add IDs to headings but don't want a TOC.
+
+```typescript
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { rehypeSlugger } from "rehype-custom-toc";
+import rehypeStringify from "rehype-stringify";
+import { unified } from "unified";
+
+const processor = unified().use(remarkParse).use(remarkRehype).use(rehypeSlugger).use(rehypeStringify);
+
+const markdown = `
+# Title
+
+This is a sample markdown paragraph.
+
+## 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>
+<h2 id="section-1">Section 1</h2>
+<h3 id="subsection-11">Subsection 1.1</h3>
+```
+
 ## Options
 
 ### `template`

package/dist/index.d.ts

@@ -38,11 +38,16 @@ interface RehypeCustomTocOptions {
      */
     ordered?: boolean;
 }
+/**
+ * Rehype plugin to add slugs to headings in the HAST tree.
+ * @returns The transformer function
+ */
+declare const rehypeSlugger: Plugin<[], Root>;
 /**
  * Rehype plugin to generate a table of contents.
  * @param userOptions Options for the plugin
- * @returns The plugin
+ * @returns The transformer function
  */
 declare const rehypeCustomToc: Plugin<[RehypeCustomTocOptions], Root>;
 export default rehypeCustomToc;
-export type { RehypeCustomTocOptions, RehypeCustomTocTemplate };
+export { type RehypeCustomTocOptions, type RehypeCustomTocTemplate, rehypeSlugger };

package/dist/index.js

@@ -26,6 +26,45 @@ const DEFAULT_OPTIONS = {
     ordered: false,
     template: defaultTemplate
 };
+/**
+ * Checks if a node is a heading element.
+ * @param node The node to check
+ * @returns True if the node is a heading element, false otherwise
+ */
+const isHeading = (node) => ["h1", "h2", "h3", "h4", "h5", "h6"].includes(node.tagName);
+/**
+ * Adds an ID to a heading element and extracts its text.
+ * @param node The heading element
+ * @param slugger The GitHubSlugger instance
+ * @returns An object containing the slug and text of the heading
+ */
+const addIdToHeading = (node, slugger) => {
+    const text = toText(node).trim();
+    // Empty-string ids should be replaced with a generated slug
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+    const slug = node.properties.id || slugger.slug(text);
+    node.properties.id = slug;
+    return { slug, text };
+};
+/**
+ * Rehype plugin to add slugs to headings in the HAST tree.
+ * @returns The transformer function
+ */
+const rehypeSlugger = () => {
+    /**
+     * The transformer function for the plugin.
+     * @param tree The HAST tree
+     */
+    const transformer = (tree) => {
+        const slugger = new GitHubSlugger();
+        visit(tree, "element", (node) => {
+            if (!isHeading(node))
+                return;
+            addIdToHeading(node, slugger);
+        });
+    };
+    return transformer;
+};
 /**
  * Generate the table of contents from the headings data.
  * @param tree The HAST tree
@@ -43,11 +82,9 @@ const generateToc = (tree, options) => {
     const headings = [];
     const slugger = new GitHubSlugger();
     visit(tree, "element", (node) => {
-        if (!["h1", "h2", "h3", "h4", "h5", "h6"].includes(node.tagName))
+        if (!isHeading(node))
             return;
-        const text = toText(node).trim();
-        const slug = node.properties["id"] || slugger.slug(text);
-        node.properties["id"] = slug;
+        const { slug, text } = addIdToHeading(node, slugger);
         // eslint-disable-next-line no-magic-numbers
         const depth = parseInt(node.tagName.slice(1), 10);
         headings.push({
@@ -100,7 +137,7 @@ const generateToc = (tree, options) => {
 /**
  * Rehype plugin to generate a table of contents.
  * @param userOptions Options for the plugin
- * @returns The plugin
+ * @returns The transformer function
  */
 const rehypeCustomToc = (userOptions) => {
     const options = { ...DEFAULT_OPTIONS, ...userOptions };
@@ -139,3 +176,4 @@ const rehypeCustomToc = (userOptions) => {
     return transformer;
 };
 export default rehypeCustomToc;
+export { rehypeSlugger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rehype-custom-toc",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "rehype plugin to generate a customizable table of contents",
   "keywords": [
     "rehype",
@@ -58,6 +58,7 @@
     "cross-env": "^10.1.0",
     "eslint": "^10.0.0",
     "prettier": "^3.7.4",
+    "rehype-parse": "^9.0.1",
     "rehype-stringify": "^10.0.1",
     "remark-comment": "^1.0.0",
     "remark-parse": "^11.0.0",