feat: introduce headindIds option to disable auto generated id for headings (#284)

Author: farnabaz

docs/content/2.syntax/3.attributes.md

@@ -204,7 +204,7 @@ A paragraph {attr="value"}
 
 ### Headings
 
-`{...}` after a heading attaches to that heading (alongside its auto-generated id):
+`{...}` after a heading attaches to that heading (alongside its auto-generated id when `headingIds` is enabled):
 
 ::code-group
 ```mdc [Syntax]

docs/content/5.api/1.parse.md

@@ -365,6 +365,7 @@ Both `parse()` and `createParse()` accept the same `ParseOptions`:
 | `autoClose` | `boolean` | `true` | Auto-close incomplete markdown syntax |
 | `html` | `boolean` | `true` | Parse embedded HTML tags into AST nodes |
 | `linkify` | `boolean` | `true` | Auto-convert URL-like text into links. Set `false` to disable |
+| `headingIds` | `boolean` | `true` | Auto-generate `id` attributes for `h1`–`h6` headings. Set `false` to disable |
 | `plugins` | `ComarkPlugin[]` | `[]` | Array of plugins to apply |
 
 ---

docs/content/5.api/3.reference.md

@@ -273,6 +273,8 @@ interface ParseOptions {
   autoUnwrap?: boolean     // default: true
   autoClose?: boolean      // default: true
   html?: boolean           // default: true
+  linkify?: boolean        // default: true
+  headingIds?: boolean     // default: true
   plugins?: ComarkPlugin[]
 }
 ```

docs/skills/comark/references/markdown-syntax.md

@@ -29,7 +29,7 @@ Comark supports all standard CommonMark and GitHub Flavored Markdown (GFM) featu
 ###### Heading 6
 ```
 
-**Note:** All headings automatically get ID attributes generated from their content for linking (e.g., `# Hello World` becomes `<h1 id="hello-world">`).
+**Note:** All headings automatically get ID attributes generated from their content for linking (e.g., `# Hello World` becomes `<h1 id="hello-world">`). Set `headingIds: false` in parse options to disable auto-generated ids.
 
 ### Text Formatting
 

packages/comark/src/internal/parse/token-processor.ts

@@ -31,21 +31,27 @@ interface ProcessState {
   headingSlugCounts: Map<string, number>
   headingStack: Array<{ level: number; id: string }>
   preservePositions: boolean
+  headingIds: boolean
 }
 
 // ─── main entry point ───────────────────────────────────────────────────────
 
+interface TokenProcessorOptions {
+  startLine?: number
+  preservePositions?: boolean
+  headingIds?: boolean
+}
+
 /**
  * Convert Markdown-It tokens to a Comark tree
  */
-export function marmdownItTokensToComarkTree(
-  tokens: any[],
-  options: { startLine: number; preservePositions: boolean } = { startLine: 0, preservePositions: false }
-): ComarkNode[] {
+export function marmdownItTokensToComarkTree(tokens: any[], opts?: TokenProcessorOptions): ComarkNode[] {
+  const options = { startLine: 0, preservePositions: false, headingIds: true, ...opts }
   const state: ProcessState = {
     headingSlugCounts: new Map<string, number>(),
     headingStack: [],
     preservePositions: options.preservePositions,
+    headingIds: options.headingIds ?? true,
   }
   const nodes: ComarkNode[] = []
 
@@ -418,12 +424,15 @@ function processBlockToken(
       state
     )
     if (children.nodes.length > 0) {
-      // Always generate ID for all headings, no exceptions
-      const textContent = extractTextContent(children.nodes)
-      const headingId = uniqueSlug(slugify(textContent), level, state)
-
-      // Merge user-supplied attrs with the auto-generated id; user `id` wins.
-      const attrs: Record<string, unknown> = { id: headingId, ...userAttrs }
+      let attrs: Record<string, unknown>
+      if (state?.headingIds) {
+        const textContent = extractTextContent(children.nodes)
+        const headingId = uniqueSlug(slugify(textContent), level, state)
+        // Merge user-supplied attrs with the auto-generated id; user `id` wins.
+        attrs = { id: headingId, ...userAttrs }
+      } else {
+        attrs = userAttrs
+      }
 
       return {
         node: [headingTag, attrs, ...children.nodes] as ComarkNode,

packages/comark/src/parse.ts

@@ -141,6 +141,7 @@ export function createParse<const TPlugins extends readonly ComarkPlugin<any, an
     let nodes = marmdownItTokensToComarkTree(state.tokens, {
       startLine: state.parsedLines,
       preservePositions: opts.streaming ?? false,
+      headingIds: options.headingIds ?? true,
     })
 
     if (autoUnwrap) {

packages/comark/src/types.ts

@@ -417,6 +417,21 @@ export interface ParseOptions<TPlugins extends readonly ComarkPlugin<any, any>[]
    */
   linkify?: boolean
 
+  /**
+   * Whether to auto-generate `id` attributes for `h1`–`h6` headings from their text content.
+   * Set `false` to skip auto-generated ids; user-supplied `id` attributes are still preserved.
+   *
+   * @default true
+   * @example
+   * // With headingIds: true (default)
+   * // # Hello World → ['h1', { id: 'hello-world' }, 'Hello World']
+   *
+   * // With headingIds: false
+   * // # Hello World → ['h1', {}, 'Hello World']
+   * // # Hello {id="custom"} → ['h1', { id: 'custom' }, 'Hello']
+   */
+  headingIds?: boolean
+
   /**
    * Additional plugins to use
    * @default []

packages/comark/test/heading-ids.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { parse } from '../src/parse'
+
+describe('headingIds option', () => {
+  it('generates id attributes by default', async () => {
+    const tree = await parse('# Hello World')
+
+    expect(tree.nodes).toEqual([['h1', { id: 'hello-world' }, 'Hello World']])
+  })
+
+  it('skips auto-generated ids when headingIds is false', async () => {
+    const tree = await parse('# Hello World', { headingIds: false })
+
+    expect(tree.nodes).toEqual([['h1', {}, 'Hello World']])
+  })
+
+  it('preserves user-supplied id when headingIds is false', async () => {
+    const tree = await parse('# Hello {id="custom"}', { headingIds: false })
+
+    expect(tree.nodes).toEqual([['h1', { id: 'custom' }, 'Hello']])
+  })
+
+  it('still generates hierarchical ids when headingIds is true', async () => {
+    const tree = await parse('# Title\n\n## Section')
+
+    expect(tree.nodes).toEqual([
+      ['h1', { id: 'title' }, 'Title'],
+      ['h2', { id: 'section' }, 'Section'],
+    ])
+  })
+})

test/bundle.test.ts

@@ -67,7 +67,7 @@ describe('package bundle size', { timeout: 60_000 }, () => {
         "@comark/react": "39.9k (58 files)",
         "@comark/svelte": "40.1k (66 files)",
         "@comark/vue": "56.0k (62 files)",
-        "comark": "363k (134 files)",
+        "comark": "364k (134 files)",
       }
     `)
   })