🧑‍💻 Make headings processing opt-in

Author: CollierCZ

README.md

@@ -16,6 +16,7 @@ Use Markdoc defaults out of the box or configure Markdoc schema to your needs.
   - [Relative imports](#relative-imports)
 - [Preprocessor Options](#preprocessor-options)
   - [Functions](#functions)
+  - [Heading IDs](#heading-ids)
   - [Nodes](#nodes)
   - [Partials](#partials)
   - [Tags](#tags)
@@ -270,6 +271,7 @@ const config = {
 | `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)                                                    |
@@ -313,6 +315,16 @@ title: Hello World
 This is a {% uppercase(markdown) %} file that is processed by `markdoc-svelte`.
 ```
 
+### Heading IDs
+
+If you want to build a table of contents for a page or just have links to specific headings, set `headingIds` to `true.
+You can add your own IDs in the original file with [annotations](https://markdoc.dev/docs/syntax#annotations)
+or they are generated automatically.
+Each heading element in the generated HTML has an `id` attribute you can use to link to directly.
+
+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).
+
 ### Nodes
 
 [Nodes](https://markdoc.dev/docs/nodes) are elements built into Markdown from the CommonMark specification.
@@ -525,16 +537,16 @@ See the example [custom node](#nodes).
 
 ### Page table of contents
 
-Each proccessed page automatically exports a `headings` property with all headings on the page and IDs for each.
-Add IDs with [annotations](https://markdoc.dev/docs/syntax#annotations) or they are generated automatically.
+When you have the [`headingIds` option](#heading-ids) set to `true`,
+each proccessed page automatically exports a `headings` property with all headings on the page and IDs for each.
 Use this list to generate a table of contents for the page, as in the following example:
 
 ```svelte
 <script lang="ts">
   let { data } = $props();
   const { frontmatter, headings } = data.page;
 
-  // Filter only h1 and h2 headings
+  // Include only h1 and h2 headings
   const filteredHeadings = headings?.filter((heading) => heading.level <= 2) ?? [];
 </script>
 

src/main.ts

@@ -23,6 +23,7 @@ const validOptionKeys: (keyof Options)[] = [
   "components",
   "extensions",
   "functions",
+  "headingIds",
   "layout",
   "linkify",
   "nodes",
@@ -67,6 +68,7 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
   const componentsPath = options.components || "$lib/components";
   const layoutPath = options.layout;
   const allowComments = options.comments ?? true;
+  const processHeadings = options.headingIds ?? false;
   const linkify = options.linkify ?? false;
   const typographer = options.typographer ?? false;
   const validationLevel = options.validationLevel || "error";
@@ -144,8 +146,13 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
       const fullConfig: Config = {
         // Start with base config loaded from the schema directory
         // Explicitly set options overwrite the base config
-        // For example, this processor's heading comes first so it's overwritten
-        nodes: { heading, ...configFromSchema.nodes, ...nodes },
+        // For example, if processing headings,
+        // This processor's heading comes first so it's overwritten
+        nodes: {
+          ...(processHeadings ? { heading } : {}), // Only include if passed as option
+          ...configFromSchema.nodes,
+          ...nodes,
+        },
         tags: { ...configFromSchema.tags, ...tags },
         functions: { ...configFromSchema.functions, ...functions },
         partials: { ...partialsFromSchema, ...partialsFromPartials },
@@ -166,7 +173,9 @@ export const markdocPreprocess = (options: Options = {}): PreprocessorGroup => {
       const transformedContent = await Markdoc.transform(ast, fullConfig);
 
       // --- Collect headings from transformed content ---
-      const headings = collectHeadings(transformedContent);
+      const headings = processHeadings
+        ? collectHeadings(transformedContent)
+        : [];
 
       // Render Markdoc AST to Svelte
       const svelteContent = render(transformedContent);

src/types.ts

@@ -39,6 +39,11 @@ export interface Options {
    * @default undefined
    */
   functions?: Config["functions"];
+  /**
+   * Whether to add IDs to all headings and generate and export a list of headings.
+   * @default false
+   */
+  headingIds?: boolean;
   /**
    * Specify a Svelte component to use as a layout for the Markdoc file.
    * Use import paths and aliases that Svelte can resolve.