fix(plugins): headings plugin has remove false by default (#187)

Author: atinux

docs/content/4.plugins/1.built-in/headings.md

@@ -18,7 +18,7 @@ links:
     variant: soft
 ---
 
-The `comark/plugins/headings` plugin extracts the page title and description from the top of a document and stores them in `tree.meta.title` and `tree.meta.description`. By default it reads the first `h1` as the title and the first `p` as the description, then removes both nodes from the tree so they are not rendered twice.
+The `comark/plugins/headings` plugin extracts the page title and description from the top of a document and stores them in `tree.meta.title` and `tree.meta.description`. By default it reads the first `h1` as the title and the first `p` as the description, keeping both nodes in the tree. Set `remove: true` to strip them so they are not rendered twice.
 
 ## Usage
 
@@ -62,7 +62,7 @@ The description check always looks at the node **immediately after** the title 
 |---|---|---|---|
 | [`titleTag`](#options-code-titletag) | `string` | `'h1'` | Element tag to extract as the page title |
 | [`descriptionTag`](#options-code-descriptiontag) | `string` | `'p'` | Element tag to extract as the page description |
-| [`remove`](#options-code-remove) | `boolean` | `true` | Remove extracted nodes from the tree after extraction |
+| [`remove`](#options-code-remove) | `boolean` | `false` | Remove extracted nodes from the tree after extraction |
 
 ### `titleTag`
 
@@ -86,13 +86,13 @@ headings({ descriptionTag: 'blockquote' })
 
 ### `remove`
 
-Whether to remove the extracted nodes from the tree after extraction. Set to `false` when you want the metadata available but still need the nodes rendered — for example, when a custom component handles the `h1` display.
+Whether to remove the extracted nodes from the tree after extraction. Set to `true` when you don't want the title and description rendered — for example, when a layout already displays them separately.
 
 ```typescript
-headings({ remove: false })
+headings({ remove: true })
 ```
 
-**Default:** `true`
+**Default:** `false`
 
 ---
 
@@ -122,7 +122,7 @@ const result = await parse(content, {
 
 console.log(result.meta.title)       // "My Page Title"
 console.log(result.meta.description) // "This is the opening paragraph used as the description."
-// result.nodes no longer contains the h1 or the first p
+// result.nodes still contains the h1 and the first p (use remove: true to strip them)
 ```
 
 ::

packages/comark/src/plugins/headings.ts

@@ -59,19 +59,19 @@ function flattenNodeText(node: ComarkNode): string {
  *    content is written to `tree.meta.description`. When no title was found,
  *    this check starts from the very first content node.
  *
- * Both nodes are removed from the tree by default so they are not rendered
- * twice. Set `remove: false` to keep them in place.
+ * By default the extracted nodes are kept in the tree. Set `remove: true`
+ * to strip them so they are not rendered twice.
  *
  * @example
  * ```ts
- * // Default — h1 as title, first paragraph as description
+ * // Default — h1 as title, first paragraph as description, nodes kept in tree
  * headings()
  *
  * // Use a blockquote as the description instead of a paragraph
  * headings({ descriptionTag: 'blockquote' })
  *
- * // Extract metadata without removing the nodes from the tree
- * headings({ remove: false })
+ * // Extract metadata and remove the matched nodes from the tree
+ * headings({ remove: true })
  * ```
  */
 export default defineComarkPlugin((options: HeadingsOptions = {}) => {

packages/comark/test/headings.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest'
+import { parse } from '../src/parse'
+import headings from '../src/plugins/headings'
+
+const CONTENT = `# My Page Title
+
+This is the description paragraph.
+
+## Section One
+
+More content here.
+`
+
+describe('headings plugin', () => {
+  it('extracts title and description into meta', async () => {
+    const tree = await parse(CONTENT, { plugins: [headings()] })
+
+    expect(tree.meta.title).toBe('My Page Title')
+    expect(tree.meta.description).toBe('This is the description paragraph.')
+  })
+
+  it('keeps extracted nodes in the tree by default (remove: false)', async () => {
+    const tree = await parse(CONTENT, { plugins: [headings()] })
+
+    const tags = tree.nodes.filter((n) => Array.isArray(n)).map((n) => (n as any)[0])
+
+    expect(tags).toContain('h1')
+    expect(tags).toContain('p')
+  })
+
+  it('removes extracted nodes when remove: true', async () => {
+    const tree = await parse(CONTENT, { plugins: [headings({ remove: true })] })
+
+    expect(tree.meta.title).toBe('My Page Title')
+    expect(tree.meta.description).toBe('This is the description paragraph.')
+
+    const tags = tree.nodes.filter((n) => Array.isArray(n)).map((n) => (n as any)[0])
+
+    expect(tags).not.toContain('h1')
+    expect(tags).toContain('h2')
+    // The first <p> (description) should be removed, but the second section content stays
+    const paragraphs = tree.nodes.filter((n) => Array.isArray(n) && (n as any)[0] === 'p')
+    expect(
+      paragraphs.every((p) => {
+        const text = Array.isArray(p) && p.length > 2 ? String(p[2]) : ''
+        return text !== 'This is the description paragraph.'
+      })
+    ).toBe(true)
+  })
+
+  it('does not set meta.title when no matching tag exists', async () => {
+    const tree = await parse('Just a paragraph.\n', { plugins: [headings()] })
+
+    expect(tree.meta.title).toBeUndefined()
+    expect(tree.meta.description).toBe('Just a paragraph.')
+  })
+
+  it('uses custom titleTag and descriptionTag', async () => {
+    const md = `## Custom Title
+
+> Lead-in quote as description.
+
+More content.
+`
+    const tree = await parse(md, {
+      plugins: [headings({ titleTag: 'h2', descriptionTag: 'blockquote' })],
+    })
+
+    expect(tree.meta.title).toBe('Custom Title')
+    expect(tree.meta.description).toBe('Lead-in quote as description.')
+  })
+})