✨ Allow for custom ID slugging functions

CollierCZ · CollierCZ · commit 5720bea72edd · 2025-08-30T22:10:40.000+02:00
diff --git a/README.md b/README.md
@@ -265,22 +265,22 @@ const config = {
 
 ## Preprocessor Options
 
-| Option            | Type                | Default                          | Description                                                               |
-| ----------------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------- |
-| `comments`        | boolean             | `true`                           | Enable [Markdown comments](https://spec.commonmark.org/0.30/#example-624) |
-| `components`      | string              | `"$lib/components"`              | Svelte components directory for custom nodes and tags                     |
-| `extensions`      | string[]            | `[".mdoc", ".md"]`               | Files to process with Markdoc                                             |
-| `functions`       | Config['functions'] | -                                | [Functions config](#functions)                                            |
-| `headingIds`      | boolean             | `false`                          | Add IDs to headings without them and include them in export               |
-| `layout`          | string              | -                                | Default layout for all processed Markdown files                           |
-| `linkify`         | boolean             | `false`                          | Auto-convert bare URLs to links                                           |
-| `nodes`           | Config['nodes']     | -                                | [Nodes config](#nodes)                                                    |
-| `partials`        | string              | -                                | [Partials](#partials) directory path                                      |
-| `schema`          | string              | `["./markdoc", "./src/markdoc"]` | Schema directory path                                                     |
-| `tags`            | Config['tags']      | -                                | [Tags config](#tags)                                                      |
-| `typographer`     | boolean             | `false`                          | Enable [typography replacements](#typographer)                            |
-| `validationLevel` | ValidationLevel     | `"error"`                        | [Validation strictness level](#validation-level)                          |
-| `variables`       | Config['variables'] | -                                | [Variables config](#variables)                                            |
+| Option            | Type                                     | Default                          | Description                                                               |
+| ----------------- | ---------------------------------------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `comments`        | boolean                                  | `true`                           | Enable [Markdown comments](https://spec.commonmark.org/0.30/#example-624) |
+| `components`      | string                                   | `"$lib/components"`              | Svelte components directory for custom nodes and tags                     |
+| `extensions`      | string[]                                 | `[".mdoc", ".md"]`               | Files to process with Markdoc                                             |
+| `functions`       | Config['functions']                      | -                                | [Functions config](#functions)                                            |
+| `headingIds`      | boolean \| `((value: string) => string)` | `false`                          | Add IDs to headings without them and include them in export               |
+| `layout`          | string                                   | -                                | Default layout for all processed Markdown files                           |
+| `linkify`         | boolean                                  | `false`                          | Auto-convert bare URLs to links                                           |
+| `nodes`           | Config['nodes']                          | -                                | [Nodes config](#nodes)                                                    |
+| `partials`        | string                                   | -                                | [Partials](#partials) directory path                                      |
+| `schema`          | string                                   | `["./markdoc", "./src/markdoc"]` | Schema directory path                                                     |
+| `tags`            | Config['tags']                           | -                                | [Tags config](#tags)                                                      |
+| `typographer`     | boolean                                  | `false`                          | Enable [typography replacements](#typographer)                            |
+| `validationLevel` | ValidationLevel                          | `"error"`                        | [Validation strictness level](#validation-level)                          |
+| `variables`       | Config['variables']                      | -                                | [Variables config](#variables)                                            |
 
 ### Functions
 
@@ -325,6 +325,28 @@ Each heading element in the generated HTML has an `id` attribute you can use to
 Each page then also exports a `headings` property: a list of all headings with their text, level, and ID.
 Use the list to generate a [table of contents](#page-table-of-contents).
 
+#### Custom ID Creation (Slugifying Function)
+
+By default, the preprocessor uses the [`slug` package](https://www.npmjs.com/package/slug).
+If you have requirements for ID creation, pass a function to the `headingIds` option.
+This function is used to generate the IDs.
+
+```javascript
+import { markdocPreprocess } from "markdoc-svelte";
+
+const customSlugger = (str: string): string => str.replaceAll(/[^a-z]/gi, "-");
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  extensions: [".svelte", ".mdoc"],
+  preprocess: [
+    markdocPreprocess({
+      headingIds: customSlugger,
+    }),
+  ],
+};
+```
+
 ### Nodes
 
 [Nodes](https://markdoc.dev/docs/nodes) are elements built into Markdown from the CommonMark specification.
@@ -591,7 +613,7 @@ export const load = async () => {
         slug: module.slug,
         frontmatter: module.frontmatter,
       };
-    }),
+    })
   );
   return { content };
 };
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -37,7 +37,7 @@
   "license": "MIT",
   "dependencies": {
     "@markdoc/markdoc": "^0.5.2",
-    "slugify": "^1.6.6",
+    "slug": "^11.0.0",
     "yaml": "^2.7.1"
   },
   "devDependencies": {
@@ -47,6 +47,7 @@
     "@rollup/plugin-typescript": "^12.1.2",
     "@tsconfig/svelte": "^5.0.4",
     "@types/node": "^22.15.2",
+    "@types/slug": "^5.0.9",
     "@vitest/coverage-v8": "^3.1.4",
     "eslint": "^9.25.1",
     "eslint-config-prettier": "^10.1.2",
diff --git a/src/headings.ts b/src/headings.ts
@@ -1,6 +1,7 @@
 import { Tag } from "@markdoc/markdoc";
 import type { RenderableTreeNode, Schema } from "@markdoc/markdoc";
-import slugify from "slugify";
+
+import type { MarkdocSvelteConfig, SluggerType } from "./types.ts";
 
 export interface Heading {
   /**
@@ -29,16 +30,14 @@ const getTextContent = (children: RenderableTreeNode[]): string => {
 };
 
 const getSlug = (
+  sluggifier: SluggerType,
   attributes: Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
   children: RenderableTreeNode[],
 ): string => {
   if (attributes.id && typeof attributes.id === "string") {
     return attributes.id;
   }
-  return slugify(getTextContent(children), {
-    lower: true,
-    strict: true,
-  }) as string;
+  return sluggifier(getTextContent(children));
 };
 /**
  * Recursively collects all heading nodes from a Markdoc AST
@@ -47,12 +46,13 @@ const getSlug = (
  */
 export function collectHeadings(
   node: RenderableTreeNode | RenderableTreeNode[],
+  sluggifier: SluggerType,
   sections: Heading[] = [],
 ): Heading[] {
   // Handle array of nodes
   if (Array.isArray(node)) {
     for (const child of node) {
-      sections.push(...collectHeadings(child));
+      sections.push(...collectHeadings(child, sluggifier));
     }
     return sections;
   }
@@ -67,7 +67,7 @@ export function collectHeadings(
       sections.push({
         level: node.attributes?.level,
         title: getTextContent(node.children),
-        id: getSlug(node.attributes, node.children),
+        id: getSlug(sluggifier, node.attributes, node.children),
       });
     }
 
@@ -79,14 +79,14 @@ export function collectHeadings(
         sections.push({
           level: parseInt(tag.name[1]),
           title: getTextContent(tag.children),
-          id: getSlug(tag.attributes, tag.children),
+          id: getSlug(sluggifier, tag.attributes, tag.children),
         });
       }
 
       // Handle node children
       if (tag.children) {
         for (const child of tag.children) {
-          collectHeadings(child, sections);
+          collectHeadings(child, sluggifier, sections);
         }
       }
     }
@@ -101,11 +101,11 @@ export const heading: Schema = {
     id: { type: String },
     level: { type: Number, required: true, default: 1 },
   },
-  transform(node, config) {
+  transform(node, config: MarkdocSvelteConfig) {
     const { level, ...attributes } = node.transformAttributes(config);
     const children = node.transformChildren(config);
 
-    const slug = getSlug(node.attributes, children);
+    const slug = getSlug(config.headingSlugger, node.attributes, children);
 
     const render = config.nodes?.heading?.render ?? `h${level}`;
 
diff --git a/src/index.ts b/src/index.ts
@@ -1,6 +1,5 @@
 export { heading as headingNode } from "./headings.ts";
 export { markdocPreprocess } from "./main.ts";
-export type { MarkdocModule } from "./types.ts";
+export type { MarkdocModule, MarkdocSvelteConfig as Config } from "./types.ts";
 
 export { default as Markdoc } from "@markdoc/markdoc";
-export type { Config } from "@markdoc/markdoc";
diff --git a/src/main.ts b/src/main.ts
@@ -1,7 +1,8 @@
 import { basename, extname } from "path";
 
 import Markdoc from "@markdoc/markdoc";
-import type { Config, ParserArgs } from "@markdoc/markdoc";
+import type { ParserArgs } from "@markdoc/markdoc";
+import slug from "slug";
 import type { PreprocessorGroup } from "svelte/compiler";
 import YAML from "yaml";
 
@@ -11,12 +12,12 @@ import {
 } from "./components.ts";
 import { handleValidationErrors } from "./errors.ts";
 import { findFirstDirectory, makePathProjectRelative } from "./files.ts";
-import { collectHeadings, heading } from "./headings.ts";
+import { collectHeadings, heading, type Heading } from "./headings.ts";
 import log from "./logs.ts";
 import loadPartials from "./partials.ts";
 import render from "./render.ts";
 import loadSchemas from "./schema.ts";
-import type { Options } from "./types.ts";
+import type { MarkdocSvelteConfig, Options } from "./types.ts";
 
 const validOptionKeys: (keyof Options)[] = [
   "comments",
@@ -45,7 +46,7 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
   for (const key in options) {
     if (!validOptionKeys.includes(key as keyof Options)) {
       log.warn(
-        `Invalid option "${key}" provided and ignored. Check the documentation for valid options.`,
+        `Invalid option "${key}" provided and ignored. Check the documentation for valid options.`
       );
     }
   }
@@ -69,6 +70,9 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
   const layoutPath = options.layout;
   const allowComments = options.comments ?? true;
   const processHeadings = options.headingIds ?? false;
+  // If passed `true`, use the default for slugging headings
+  // Otherwise, use the passed function
+  const headingSlugger = typeof processHeadings === "boolean" ? slug : processHeadings;
   const linkify = options.linkify ?? false;
   const typographer = options.typographer ?? false;
   const validationLevel = options.validationLevel || "error";
@@ -117,9 +121,9 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
 
       // Prepare to load schemas & partials
       const dependencies: string[] = [];
-      let configFromSchema: Config = {};
-      let partialsFromSchema: Config["partials"] = {};
-      let partialsFromPartials: Config["partials"] = {};
+      let configFromSchema: MarkdocSvelteConfig = {};
+      let partialsFromSchema: MarkdocSvelteConfig["partials"] = {};
+      let partialsFromPartials: MarkdocSvelteConfig["partials"] = {};
 
       // Discover optional schema directory
       const schemaDir = findFirstDirectory(schemaPaths);
@@ -143,7 +147,7 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
       }
 
       // Assemble full config
-      const fullConfig: Config = {
+      const fullConfig: MarkdocSvelteConfig = {
         // Start with base config loaded from the schema directory
         // Explicitly set options overwrite the base config
         // For example, if processing headings,
@@ -158,6 +162,7 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
         partials: { ...partialsFromSchema, ...partialsFromPartials },
         // Make $frontmatter available as variable
         variables: { ...configFromSchema.variables, ...variables, frontmatter },
+        headingSlugger
       };
 
       // Validate Markdoc AST
@@ -172,10 +177,14 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
       // eslint-disable-next-line @typescript-eslint/await-thenable
       const transformedContent = await Markdoc.transform(ast, fullConfig);
 
-      // --- Collect headings from transformed content ---
-      const headings = processHeadings
-        ? collectHeadings(transformedContent)
-        : [];
+      // Collect headings from transformed content
+      const getHeadings = (): Heading[] => {
+        if (processHeadings) {
+          return collectHeadings(transformedContent, headingSlugger);
+        }
+        return [];
+      };
+      const headings = getHeadings()
 
       // Render Markdoc AST to Svelte
       const svelteContent = render(transformedContent);
@@ -203,7 +212,7 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
         extractUsedSvelteComponents(transformedContent);
       const componentImportStatements = getComponentImports(
         usedSvelteComponentNames,
-        componentsPath,
+        componentsPath
       );
 
       // Construct script tag content
diff --git a/src/types.ts b/src/types.ts
@@ -43,7 +43,7 @@ export interface Options {
    * Whether to add IDs to all headings and generate and export a list of headings.
    * @default false
    */
-  headingIds?: boolean;
+  headingIds?: boolean | SluggerType;
   /**
    * Specify a Svelte component to use as a layout for the Markdoc file.
    * Use import paths and aliases that Svelte can resolve.
@@ -120,3 +120,9 @@ export interface MarkdocModule {
    */
   headings?: Heading[];
 }
+
+export type SluggerType = ((value: string) => string)
+
+export interface MarkdocSvelteConfig extends Config {
+  headingSlugger?: SluggerType
+}
diff --git a/test/__snapshots__/heading.test.ts.snap b/test/__snapshots__/heading.test.ts.snap
@@ -17,3 +17,19 @@ exports[`Headings > adds IDs and exports headings even when the custom heading i
 </script>
 <article><HeadingComponent id="this-is-some-basic-markdoc">This is some basic Markdoc</HeadingComponent><p>With a paragraph.</p><HeadingComponent id="more-fancy-stuff">More fancy stuff</HeadingComponent><p>Content. Such great content.</p></article>"
 `;
+
+exports[`Headings > adds IDs when passed a custom slugifying function 1`] = `
+"<script module>
+	export const slug = "test";
+	export const headings = [{"level":1,"title":"This is some basic Markdoc","id":"This-is-some-basic-Markdoc"},{"level":2,"title":"More fancy stuff","id":"More-fancy-stuff"}];
+</script>
+<article><h1 id="This-is-some-basic-Markdoc">This is some basic Markdoc</h1><p>With a paragraph.</p><h2 id="More-fancy-stuff">More fancy stuff</h2><p>Content. Such great content.</p></article>"
+`;
+
+exports[`Headings > adds IDs when passed a custom slugifying function even for custom headings 1`] = `
+"<script module>
+	export const slug = "test";
+	export const headings = [{"level":1,"title":"This is some basic Markdoc","id":"This-is-some-basic-Markdoc"},{"level":1,"title":"More fancy stuff","id":"More-fancy-stuff"}];
+</script>
+<article><h1 class="custom-heading" id="This-is-some-basic-Markdoc">This is some basic Markdoc</h1><p>With a paragraph.</p><h1 class="custom-heading" id="More-fancy-stuff">More fancy stuff</h1><p>Content. Such great content.</p></article>"
+`;
diff --git a/test/heading.test.ts b/test/heading.test.ts
