feat(plugins): allow disabling headings title/description extraction (#188)

Author: atinux

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

@@ -60,26 +60,32 @@ The description check always looks at the node **immediately after** the title 
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| [`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 |
+| [`titleTag`](#options-code-titletag) | `string \| false` | `'h1'` | Element tag to extract as the page title, or `false` to disable |
+| [`descriptionTag`](#options-code-descriptiontag) | `string \| false` | `'p'` | Element tag to extract as the page description, or `false` to disable |
 | [`remove`](#options-code-remove) | `boolean` | `false` | Remove extracted nodes from the tree after extraction |
 
 ### `titleTag`
 
-The element tag to read the title from.
+The element tag to read the title from. Set to `false` to disable title extraction entirely.
 
 ```typescript
 headings({ titleTag: 'h2' })
+
+// Disable title extraction
+headings({ titleTag: false })
 ```
 
 **Default:** `'h1'`
 
 ### `descriptionTag`
 
-The element tag to read the description from. Use `'blockquote'` if you prefer a block quote as the lead-in description.
+The element tag to read the description from. Use `'blockquote'` if you prefer a block quote as the lead-in description. Set to `false` to disable description extraction entirely.
 
 ```typescript
 headings({ descriptionTag: 'blockquote' })
+
+// Disable description extraction
+headings({ descriptionTag: false })
 ```
 
 **Default:** `'p'`

packages/comark/src/plugins/headings.ts

@@ -4,15 +4,17 @@ import { defineComarkPlugin } from '../utils/helpers.ts'
 export interface HeadingsOptions {
   /**
    * Tag to extract as title and set to `tree.meta.title`.
+   * Set to `false` to disable title extraction.
    * @default 'h1'
    */
-  titleTag?: string
+  titleTag?: string | false
   /**
    * Tag to extract as description and set to `tree.meta.description`.
    * Useful alternatives: `'blockquote'`
+   * Set to `false` to disable description extraction.
    * @default 'p'
    */
-  descriptionTag?: string
+  descriptionTag?: string | false
   /**
    * Whether to remove the extracted nodes from the tree.
    * @default false
@@ -72,6 +74,12 @@ function flattenNodeText(node: ComarkNode): string {
  *
  * // Extract metadata and remove the matched nodes from the tree
  * headings({ remove: true })
+ *
+ * // Disable title extraction, only extract description
+ * headings({ titleTag: false })
+ *
+ * // Disable description extraction, only extract title
+ * headings({ descriptionTag: false })
  * ```
  */
 export default defineComarkPlugin((options: HeadingsOptions = {}) => {
@@ -88,18 +96,23 @@ export default defineComarkPlugin((options: HeadingsOptions = {}) => {
       let titleNodeIndex = -1
       let descriptionNodeIndex = -1
 
-      const first = contentNodes[0]
-      if (first && getTag(first) === titleTag) {
-        titleNodeIndex = nodes.indexOf(first)
-        state.tree.meta.title = flattenNodeText(first)
+      let nextContentIndex = 0
+
+      if (titleTag !== false) {
+        const first = contentNodes[0]
+        if (first && getTag(first) === titleTag) {
+          titleNodeIndex = nodes.indexOf(first)
+          state.tree.meta.title = flattenNodeText(first)
+          nextContentIndex = 1
+        }
       }
 
-      // Description is the first content node after the (optional) title
-      const afterTitle = titleNodeIndex !== -1 ? contentNodes.slice(1) : contentNodes
-      const second = afterTitle[0]
-      if (second && getTag(second) === descriptionTag) {
-        descriptionNodeIndex = nodes.indexOf(second)
-        state.tree.meta.description = flattenNodeText(second)
+      if (descriptionTag !== false) {
+        const candidate = contentNodes[nextContentIndex]
+        if (candidate && getTag(candidate) === descriptionTag) {
+          descriptionNodeIndex = nodes.indexOf(candidate)
+          state.tree.meta.description = flattenNodeText(candidate)
+        }
       }
 
       if (remove) {

packages/comark/test/headings.test.ts

@@ -55,6 +55,30 @@ describe('headings plugin', () => {
     expect(tree.meta.description).toBe('Just a paragraph.')
   })
 
+  it('disables title extraction with titleTag: false', async () => {
+    const md = 'Just a paragraph.\n'
+    const tree = await parse(md, { plugins: [headings({ titleTag: false })] })
+
+    expect(tree.meta.title).toBeUndefined()
+    expect(tree.meta.description).toBe('Just a paragraph.')
+  })
+
+  it('disables description extraction with descriptionTag: false', async () => {
+    const tree = await parse(CONTENT, { plugins: [headings({ descriptionTag: false })] })
+
+    expect(tree.meta.title).toBe('My Page Title')
+    expect(tree.meta.description).toBeUndefined()
+  })
+
+  it('disables both with titleTag: false and descriptionTag: false', async () => {
+    const tree = await parse(CONTENT, {
+      plugins: [headings({ titleTag: false, descriptionTag: false })],
+    })
+
+    expect(tree.meta.title).toBeUndefined()
+    expect(tree.meta.description).toBeUndefined()
+  })
+
   it('uses custom titleTag and descriptionTag', async () => {
     const md = `## Custom Title