rehype-slug-link 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 adhi-jp
+
+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,193 @@
+# rehype-slug-link
+
+[![build status](https://github.com/adhi-jp/rehype-slug-link/actions/workflows/ci.yml/badge.svg)](https://github.com/adhi-jp/rehype-slug-link/actions)
+[![npm version](https://img.shields.io/npm/v/rehype-slug-link.svg)](https://www.npmjs.com/package/rehype-slug-link)
+[![codecov](https://codecov.io/gh/adhi-jp/rehype-slug-link/graph/badge.svg?token=2NJE12TPJX)](https://codecov.io/gh/adhi-jp/rehype-slug-link)
+[![bundle size](https://deno.bundlejs.com/?q=rehype-slug-link&badge)](https://bundlejs.com/?q=rehype-slug-link)
+
+A [rehype](https://github.com/rehypejs/rehype) plugin that converts custom link syntax (e.g. `[{#slug}]`) in text nodes into anchor links to headings, by collecting heading IDs and their text content.
+
+---
+
+## Overview
+
+**rehype-slug-link** is a [unified](https://github.com/unifiedjs/unified) ([rehype](https://github.com/rehypejs/rehype)) plugin that enables you to write internal links to headings using a customizable inline syntax. It scans the document for headings, collects their IDs and text, and replaces matching patterns in text nodes with anchor links to those headings.
+
+- **Customizable link syntax**: Default is `[{#slug}]`, but any RegExp can be used.
+- **Flexible matching**: Supports multiple links per paragraph, deeply nested structures, and custom fallback behaviors.
+- **Unicode normalization**: Optionally normalize heading text and slugs.
+- **TypeScript support**: Includes type definitions.
+
+---
+
+## When Should You Use This Plugin?
+
+Use **rehype-slug-link** if you want:
+
+- To write internal links to headings using a simple, readable inline syntax.
+- To support custom or non-standard link notations in your markdown/HTML.
+- To automatically convert inline references to anchor links, even in complex or deeply nested content.
+- To control how unmatched or invalid slugs are handled.
+- To work with multilingual or Unicode content.
+
+---
+
+## Installation
+
+```sh
+npm install rehype-slug-link
+```
+
+---
+
+## Usage Example
+
+```js
+import { rehype } from "rehype";
+import rehypeSlug from "rehype-slug";
+import rehypeSlugLink from "rehype-slug-link";
+
+const file = await rehype()
+  .use(rehypeSlug) // Ensure headings have IDs
+  .use(rehypeSlugLink)
+  .process("<h1>Introduction</h1><p>See [{#introduction}]</p>");
+
+console.log(String(file));
+// <h1 id="introduction">Introduction</h1><p>See <a href="#introduction">Introduction</a></p>
+```
+
+### Custom Pattern Example
+
+```js
+import { rehype } from "rehype";
+import rehypeSlug from "rehype-slug";
+import rehypeSlugLink from "rehype-slug-link";
+
+const file = await rehype()
+  .use(rehypeSlug)
+  .use(rehypeSlugLink, { pattern: /\[link:([^\]]+)\]/g })
+  .process("<h1>Intro</h1><p>See [link:intro]</p>");
+
+console.log(String(file));
+// <h1 id="intro">Intro</h1><p>See <a href="#intro">Intro</a></p>
+```
+
+### Multiple Links Example
+
+```html
+<!-- Input -->
+<h1>Chapter 1</h1>
+<h2>Chapter 2</h2>
+<p>Read [{#chapter-1}] before [{#chapter-2}].</p>
+
+<!-- Output -->
+<h1 id="chapter-1">Chapter 1</h1>
+<h2 id="chapter-2">Chapter 2</h2>
+<p>
+  Read <a href="#chapter-1">Chapter 1</a> before
+  <a href="#chapter-2">Chapter 2</a>.
+</p>
+```
+
+### With Custom Heading IDs
+
+```js
+import { rehype } from "rehype";
+import rehypeHeadingSlug from "rehype-heading-slug";
+import rehypeSlugLink from "rehype-slug-link";
+
+const file = await rehype()
+  .use(rehypeHeadingSlug) // Supports {#custom-id} syntax
+  .use(rehypeSlugLink)
+  .process("<h1>Advanced Topics {#advanced}</h1><p>See [{#advanced}]</p>");
+
+console.log(String(file));
+// <h1 id="advanced">Advanced Topics</h1><p>See <a href="#advanced">Advanced Topics</a></p>
+```
+
+---
+
+## Advanced Examples
+
+### Fallback to Heading Text
+
+```js
+import { rehype } from "rehype";
+import rehypeSlug from "rehype-slug";
+import rehypeSlugLink from "rehype-slug-link";
+
+const file = await rehype()
+  .use(rehypeSlug)
+  .use(rehypeSlugLink, {
+    fallbackToHeadingText: true,
+    pattern: /\[text:([^\]]+)\]/g,
+  })
+  .process("<h1>Introduction</h1><p>See [text:Introduction]</p>");
+
+console.log(String(file));
+// <h1 id="introduction">Introduction</h1><p>See <a href="#introduction">Introduction</a></p>
+```
+
+### Unicode Normalization
+
+```js
+import { rehype } from "rehype";
+import rehypeHeadingSlug from "rehype-heading-slug";
+import rehypeSlugLink from "rehype-slug-link";
+
+const file = await rehype()
+  .use(rehypeHeadingSlug, { normalizeUnicode: true })
+  .use(rehypeSlugLink, { normalizeUnicode: true })
+  .process("<h1>café</h1><p>See [{#cafe}]</p>");
+
+console.log(String(file));
+// <h1 id="cafe">café</h1><p>See <a href="#cafe">café</a></p>
+```
+
+---
+
+## API
+
+### `rehype().use(rehypeSlugLink[, options])`
+
+Replaces custom link syntax in text nodes with anchor links to headings, based on collected heading IDs and text.
+
+#### Options
+
+All options are optional:
+
+| Name                    | Type    | Default                        | Description                                                                                                                                                                                                                                                        |
+| ----------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `pattern`               | RegExp  | `/\[\{#([a-zA-Z0-9-_]+)\}\]/g` | Regular expression to match link syntax. Must have a capture group for the slug.                                                                                                                                                                                   |
+| `patternGroupMissing`   | string  | `"wrap"`                       | If `pattern` has no capture group: `"wrap"` (wrap whole pattern), or `"error"` (throw error).                                                                                                                                                                      |
+| `fallbackToHeadingText` | boolean | `false`                        | If `true`, use heading text as slug if ID not found.                                                                                                                                                                                                               |
+| `invalidSlug`           | string  | `"convert"`                    | How to handle invalid slugs: `"convert"` (auto-fix) or `"error"` (throw error).                                                                                                                                                                                    |
+| `maintainCase`          | boolean | `false`                        | Preserve case when generating slugs.                                                                                                                                                                                                                               |
+| `normalizeUnicode`      | boolean | `false`                        | Normalize Unicode characters in slugs and heading text. Only converts Latin-based accented characters to ASCII equivalents, preserving other character systems (Cyrillic, CJK, etc.). Enables case-insensitive matching between normalized slugs and heading text. |
+
+---
+
+## Security
+
+**⚠️ Important:** This plugin generates anchor links based on heading IDs and text content. If your content is user-generated, always use [rehype-sanitize](https://github.com/rehypejs/rehype-sanitize) to prevent [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) and DOM clobbering risks.
+
+---
+
+## Related Plugins
+
+- [rehype-slug](https://github.com/rehypejs/rehype-slug): Simple plugin for generating heading slugs.
+- [rehype-slug-custom-id](https://github.com/playfulprogramming/rehype-slug-custom-id): Simple ID assignment with explicit slug notation support.
+- [rehype-heading-slug](https://github.com/adhi-jp/rehype-heading-slug): Heading slugger with explicit slug notation and additional options.
+
+---
+
+## AI-Assisted Development
+
+This project was developed with the help of GitHub Copilot and other generative AI tools.  
+**Disclaimer:** Please review and test thoroughly before using in production.
+
+---
+
+## License
+
+[MIT License](./LICENSE) © adhi-jp

package/index.d.ts

@@ -0,0 +1 @@
+export { default, type RehypeSlugLinkOptions } from "./lib/index.js";

package/index.js

@@ -0,0 +1 @@
+export { default } from "./lib/index.js";

package/lib/index.d.ts

@@ -0,0 +1,62 @@
+import type { Transformer } from "unified";
+import type { Root } from "hast";
+
+/**
+ * Configuration options for the rehype-slug-link plugin.
+ */
+export interface RehypeSlugLinkOptions {
+  /**
+   * Link syntax regular expression pattern.
+   * @default /\[\{#([a-zA-Z0-9-_\u00C0-\uFFFF]+)\}\]/g
+   */
+  pattern?: RegExp;
+
+  /**
+   * Behavior when pattern has no capture groups.
+   * - 'wrap': Automatically wrap the pattern with capture group
+   * - 'error': Throw an error
+   * @default 'wrap'
+   */
+  patternGroupMissing?: "wrap" | "error";
+
+  /**
+   * Use heading text as slug if id not found.
+   * @default false
+   */
+  fallbackToHeadingText?: boolean;
+
+  /**
+   * How to handle invalid slugs.
+   * - 'convert': Convert invalid slugs using github-slugger
+   * - 'error': Throw an error
+   * @default 'convert'
+   */
+  invalidSlug?: "convert" | "error";
+
+  /**
+   * Preserve case when generating slugs.
+   * @default false
+   */
+  maintainCase?: boolean;
+
+  /**
+   * Normalize Unicode characters to ASCII equivalents.
+   * Only converts Latin-based accented characters, preserving other character systems
+   * (Cyrillic, CJK, etc.). Uses NFD normalization to decompose characters, removes
+   * combining diacritical marks, and converts special characters like æ→ae, ø→o, etc.
+   * @default false
+   */
+  normalizeUnicode?: boolean;
+}
+
+/**
+ * Rehype plugin that converts link syntax to heading links.
+ *
+ * @param options - Plugin configuration options
+ * @returns The transformer function
+ */
+declare function rehypeSlugLink(
+  options?: RehypeSlugLinkOptions,
+): Transformer<Root, Root>;
+
+export default rehypeSlugLink;

package/lib/index.js

@@ -0,0 +1,404 @@
+import { visit } from "unist-util-visit";
+import GithubSlugger from "github-slugger";
+
+/**
+ * @typedef {import('./index.d.ts').RehypeSlugLinkOptions} RehypeSlugLinkOptions
+ * @typedef {import('unified').Transformer<import('hast').Root, import('hast').Root>} UnifiedTransformer
+ * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('hast').Node} HastNode
+ * @typedef {import('hast').Element} HastElement
+ * @typedef {import('hast').Text} HastText
+ * @typedef {import('hast').Parent} HastParent
+ * @typedef {import('hast').Comment} HastComment
+ */
+
+/**
+ * @typedef {Object} HeadingMaps
+ * @property {Record<string, string>} idToText - Maps heading IDs to text content
+ * @property {Record<string, string>} textToId - Maps text content to heading IDs
+ */
+
+/**
+ * @typedef {Object} ProcessedMatch
+ * @property {string} raw - Original matched text
+ * @property {string} slug - Processed slug
+ * @property {number} index - Start index in text
+ * @property {number} lastIndex - End index in text
+ */
+
+/**
+ * Rehype plugin that converts link syntax to heading links.
+ *
+ * @param {RehypeSlugLinkOptions} [options={}] - Plugin configuration
+ * @returns {UnifiedTransformer} The transformer function
+ */
+export default function rehypeSlugLink(options = {}) {
+  const config = normalizeOptions(options);
+  const pattern = ensurePatternHasCaptureGroup(
+    config.pattern,
+    config.patternGroupMissing,
+  );
+
+  return (tree) => {
+    // Early return if already processed
+    if (tree.data?.rehypeSlugLinkProcessed) {
+      return tree;
+    }
+
+    const headingMaps = collectHeadingMaps(tree, config);
+    processTextNodes(tree, pattern, headingMaps, config);
+
+    // Mark as processed
+    (tree.data ??= {}).rehypeSlugLinkProcessed = true;
+
+    return tree;
+  };
+}
+
+/**
+ * Normalizes and validates plugin options.
+ * @param {RehypeSlugLinkOptions} options - Raw options from user
+ * @returns {Required<RehypeSlugLinkOptions>} Normalized options with defaults
+ */
+function normalizeOptions(options) {
+  return {
+    pattern: options.pattern ?? /\[\{#([a-zA-Z0-9-_\u00C0-\uFFFF]+)\}\]/g,
+    patternGroupMissing: options.patternGroupMissing ?? "wrap",
+    fallbackToHeadingText: options.fallbackToHeadingText ?? false,
+    invalidSlug: options.invalidSlug ?? "convert",
+    maintainCase: options.maintainCase ?? false,
+    normalizeUnicode: options.normalizeUnicode ?? false,
+  };
+}
+
+/**
+ * Ensures the pattern has at least one capture group.
+ * @param {RegExp} pattern - The pattern to check
+ * @param {'wrap'|'error'} patternGroupMissing - Behavior when no groups found
+ * @returns {RegExp} Pattern with guaranteed capture group
+ * @throws {Error} When patternGroupMissing is 'error' and no groups found
+ */
+function ensurePatternHasCaptureGroup(pattern, patternGroupMissing) {
+  // Efficiently count capture groups using match
+  const groupCount = (pattern.source.match(/\((?!\?[:?!])/g) || []).length;
+
+  if (groupCount === 0) {
+    if (patternGroupMissing === "wrap") {
+      return new RegExp(`(${pattern.source})`, pattern.flags);
+    }
+    throw new Error("rehypeSlugLink: pattern must contain a capture group");
+  }
+
+  return pattern;
+}
+
+/**
+ * Collects mappings between heading IDs and text content.
+ * @param {HastRoot} tree - The HAST tree to traverse
+ * @param {Required<RehypeSlugLinkOptions>} config - Plugin configuration
+ * @returns {HeadingMaps} Heading mappings
+ */
+function collectHeadingMaps(tree, config) {
+  const headingMaps = { idToText: {}, textToId: {} };
+
+  visit(tree, (/** @type {HastNode} */ node) => {
+    if (
+      node.type === "element" &&
+      /^h[1-6]$/.test(/** @type {HastElement} */ (node).tagName) &&
+      /** @type {HastElement} */ (node).properties?.id
+    ) {
+      let text = extractText(/** @type {HastElement} */ (node));
+      if (config.normalizeUnicode) {
+        text = normalizeUnicodeToAscii(text);
+      }
+      const id = /** @type {HastElement} */ (node).properties.id;
+      headingMaps.idToText[id] = text;
+      headingMaps.textToId[text] = id;
+    }
+  });
+
+  return headingMaps;
+}
+
+/**
+ * Processes text nodes in the tree to convert link syntax.
+ * @param {HastRoot} tree - The HAST tree to process
+ * @param {RegExp} pattern - The pattern to match against
+ * @param {HeadingMaps} headingMaps - Heading mappings
+ * @param {Required<RehypeSlugLinkOptions>} config - Plugin configuration
+ */
+function processTextNodes(tree, pattern, headingMaps, config) {
+  const textNodesToProcess = [];
+
+  // Collect text nodes that need processing
+  visit(
+    tree,
+    "text",
+    (
+      /** @type {HastText} */ node,
+      /** @type {number} */ index,
+      /** @type {HastParent} */ parent,
+    ) => {
+      if (shouldSkipTextNode(node, parent)) {
+        return;
+      }
+
+      // Quick check with test() before expensive processing
+      pattern.lastIndex = 0;
+      if (pattern.test(node.value)) {
+        textNodesToProcess.push({ node, index, parent });
+      }
+    },
+  );
+
+  // Process collected text nodes
+  for (const { node, index, parent } of textNodesToProcess) {
+    /* v8 ignore start */
+    // This line is unreachable because:
+    // 1. textNodesToProcess only contains nodes that passed the filter check
+    // 2. The same condition was already checked during collection
+    // 3. No code between collection and processing modifies the node.data.rehypeSlugLinkProcessed flag
+    // This check exists as defensive programming for potential future code changes
+    if (node.data?.rehypeSlugLinkProcessed) continue;
+    /* v8 ignore stop */
+
+    const replacementNodes = convertLinkSyntaxInText(
+      node.value,
+      pattern,
+      headingMaps,
+      config,
+    );
+
+    if (
+      replacementNodes.length === 1 &&
+      replacementNodes[0].type === "text" &&
+      replacementNodes[0].value === node.value
+    ) {
+      (node.data ??= {}).rehypeSlugLinkProcessed = true;
+      continue;
+    }
+
+    // Mark all replacement nodes as processed
+    for (const newNode of replacementNodes) {
+      (newNode.data ??= {}).rehypeSlugLinkProcessed = true;
+    }
+
+    if (parent && typeof index === "number") {
+      parent.children.splice(index, 1, ...replacementNodes);
+    }
+  }
+}
+
+/**
+ * Determines if a text node should be skipped during processing.
+ * @param {HastText} node - The text node to check
+ * @param {HastParent} parent - The parent node
+ * @returns {boolean} True if the node should be skipped
+ */
+function shouldSkipTextNode(node, parent) {
+  return (
+    node.data?.rehypeSlugLinkProcessed ||
+    (parent?.type === "element" &&
+      /** @type {HastElement} */ (parent).tagName === "a") ||
+    !node.value
+  );
+}
+
+/**
+ * Finds all matches of the pattern in text efficiently.
+ * @param {string} text - The text to search in
+ * @param {RegExp} pattern - The pattern to match
+ * @param {Required<RehypeSlugLinkOptions>} config - Plugin configuration
+ * @returns {Array<ProcessedMatch>} Found matches
+ */
+function findAllMatches(text, pattern, config) {
+  const matches = [];
+  let match;
+  let iterationCount = 0;
+  const maxIterations = text.length + 1;
+
+  // Reset lastIndex to ensure consistent behavior
+  pattern.lastIndex = 0;
+
+  while (
+    (match = pattern.exec(text)) !== null &&
+    iterationCount < maxIterations
+  ) {
+    iterationCount++;
+
+    let slug = match[1] || match[0];
+    if (config.normalizeUnicode) {
+      slug = normalizeUnicodeToAscii(slug);
+    }
+
+    const processedSlug = processSlug(slug, config);
+    matches.push({
+      raw: match[0],
+      slug: processedSlug,
+      index: match.index,
+      lastIndex: pattern.lastIndex,
+    });
+
+    // Prevent infinite loops on zero-width matches
+    if (pattern.lastIndex === match.index) {
+      pattern.lastIndex++;
+    }
+
+    if (pattern.lastIndex > text.length) break;
+  }
+
+  return matches;
+}
+
+/**
+ * Converts link syntax in text to an array of nodes efficiently.
+ * @param {string} text - The text to process
+ * @param {RegExp} pattern - The pattern to match
+ * @param {HeadingMaps} headingMaps - Heading mappings
+ * @param {Required<RehypeSlugLinkOptions>} config - Plugin configuration
+ * @returns {Array<HastText | HastElement>} Array of text and element nodes
+ */
+function convertLinkSyntaxInText(text, pattern, headingMaps, config) {
+  const matches = findAllMatches(text, pattern, config);
+
+  /* v8 ignore start */
+  if (matches.length === 0) {
+    // This line is unreachable because:
+    // 1. convertLinkSyntaxInText is only called when pattern.test(node.value) returns true in processTextNodes (line 128)
+    // 2. findAllMatches resets pattern.lastIndex = 0 (line 181), ensuring exec() will find the same matches as test()
+    // 3. Therefore, if test() found matches, exec() will also find matches, making matches.length > 0 always true
+    // This return exists as defensive programming for potential future code changes
+    return [{ type: "text", value: text }];
+  }
+  /* v8 ignore stop */
+
+  const nodes = [];
+  let lastIndex = 0;
+
+  for (const match of matches) {
+    // Add text before match
+    if (match.index > lastIndex) {
+      nodes.push({ type: "text", value: text.slice(lastIndex, match.index) });
+    }
+
+    // Add link node or fallback to original text
+    const linkNode = createLinkNode(match.slug, headingMaps, config);
+    nodes.push(linkNode || { type: "text", value: match.raw });
+
+    lastIndex = match.index + match.raw.length;
+  }
+
+  // Add remaining text
+  if (lastIndex < text.length) {
+    nodes.push({ type: "text", value: text.slice(lastIndex) });
+  }
+
+  return nodes;
+}
+
+/**
+ * Normalize Unicode characters to ASCII equivalents
+ * Only converts Latin-based accented characters, preserving other character systems
+ * (Cyrillic, CJK, etc.)
+ * @param {string} text - The text to normalize
+ * @returns {string} The normalized text
+ */
+function normalizeUnicodeToAscii(text) {
+  return text
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[æ]/g, "ae")
+    .replace(/[Æ]/g, "AE")
+    .replace(/[ø]/g, "o")
+    .replace(/[Ø]/g, "O")
+    .replace(/[þ]/g, "th")
+    .replace(/[Þ]/g, "TH")
+    .replace(/[ð]/g, "dh")
+    .replace(/[Ð]/g, "DH")
+    .replace(/[ß]/g, "ss")
+    .normalize("NFC");
+}
+
+/**
+ * Processes and validates a slug.
+ * @param {string} slug - The slug to process
+ * @param {Required<RehypeSlugLinkOptions>} config - Plugin configuration
+ * @returns {string} Processed slug
+ * @throws {Error} When invalidSlug is 'error' and slug is invalid
+ */
+function processSlug(slug, config) {
+  if (/^[a-zA-Z0-9\-_]+$/.test(slug)) {
+    return slug;
+  }
+
+  if (config.invalidSlug === "convert") {
+    const slugger = new GithubSlugger();
+    return slugger.slug(slug, config.maintainCase);
+  }
+
+  throw new Error(`rehypeSlugLink: invalid slug: ${slug}`);
+}
+
+/**
+ * Creates a link node for the given slug.
+ * @param {string} slug - The slug to create a link for
+ * @param {HeadingMaps} headingMaps - Heading mappings
+ * @param {Required<RehypeSlugLinkOptions>} config - Plugin configuration
+ * @returns {HastElement | null} Link element or null if not found
+ */
+function createLinkNode(slug, headingMaps, config) {
+  let headingText = headingMaps.idToText[slug];
+  let id = slug;
+
+  // If not found and normalizeUnicode is enabled, try case-insensitive normalized matching
+  if (!headingText && config.normalizeUnicode) {
+    const normalizedSlug = normalizeUnicodeToAscii(slug).toLowerCase();
+
+    // Search for a heading text that normalizes to the same value (case-insensitive)
+    for (const [headingId, text] of Object.entries(headingMaps.idToText)) {
+      const normalizedText = normalizeUnicodeToAscii(text).toLowerCase();
+      if (normalizedText === normalizedSlug) {
+        headingText = text;
+        id = headingId;
+        break;
+      }
+    }
+  }
+
+  if (!headingText && config.fallbackToHeadingText) {
+    id = headingMaps.textToId[slug];
+    headingText = slug;
+  }
+
+  return headingText && id
+    ? {
+        type: "element",
+        tagName: "a",
+        properties: { href: `#${id}` },
+        children: [{ type: "text", value: headingText }],
+      }
+    : null;
+}
+
+/**
+ * Extracts text content from a node recursively.
+ * @param {HastElement | HastText | HastComment} node - The node to extract text from
+ * @returns {string} The extracted text content
+ */
+function extractText(node) {
+  if (node.type === "text") {
+    return node.value;
+  }
+
+  if ("children" in node && node.children) {
+    return node.children.map(extractText).join("");
+    /* v8 ignore start */
+  }
+
+  // This line is unreachable because:
+  // 1. All HAST Element nodes have 'children' property (even void elements have empty arrays)
+  // 2. Text and Comment nodes are handled by previous conditions
+  // 3. Other node types are not passed to this function in the current implementation
+  return "";
+}
+/* v8 ignore stop */

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "rehype-slug-link",
+  "version": "1.0.0",
+  "description": "A rehype plugin that converts custom link syntax to heading links",
+  "author": "adhi-jp",
+  "license": "MIT",
+  "keywords": [
+    "rehype",
+    "plugin",
+    "heading",
+    "link",
+    "slug"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adhi-jp/rehype-slug-link.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adhi-jp/rehype-slug-link/issues"
+  },
+  "homepage": "https://github.com/adhi-jp/rehype-slug-link#readme",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/"
+  ],
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/unist": "^3.0.3",
+    "@vitest/coverage-v8": "^3.2.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.0",
+    "prettier": "^3.5.3",
+    "rehype": "^13.0.2",
+    "rehype-slug": "^6.0.0",
+    "typescript": "^5.8.3",
+    "unified": "^11.0.5",
+    "vitest": "^3.2.3"
+  },
+  "dependencies": {
+    "github-slugger": "^2.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check:strict": "tsc --noEmit --skipLibCheck false",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  }
+}