add new "substitute" behavior

lib/index.js

@@ -8,7 +8,7 @@
  */
 
 /**
- * @typedef {'after' | 'append' | 'before' | 'prepend' | 'wrap'} Behavior
+ * @typedef {'after' | 'append' | 'before' | 'prepend' | 'wrap' | 'substitute'} Behavior
  *   Behavior.
  *
  * @callback Build
@@ -103,15 +103,36 @@ export default function rehypeAutolinkHeadings(options) {
   /** @type {import('unist-util-visit').Visitor<Element>} */
   let method
 
-  if (behavior === 'after' || behavior === 'before') {
-    method = around
-  } else if (behavior === 'wrap') {
-    method = wrap
-  } else {
-    method = inject
+  switch (behavior) {
+    case 'after':
+    case 'before': {
+      method = around
+      break
+    }
+
+    case 'wrap': {
+      method = wrap
+      break
+    }
+
+    case 'substitute': {
+      method = substitute
+
+      if (!props) {
+        props = {tabIndex: -1}
+      }
+
+      break
+    }
 
-    if (!props) {
-      props = {ariaHidden: 'true', tabIndex: -1}
+    default: {
+      method = inject
+
+      if (!props) {
+        props = {ariaHidden: 'true', tabIndex: -1}
+      }
+
+      break
     }
   }
 
@@ -169,6 +190,13 @@ export default function rehypeAutolinkHeadings(options) {
     node.children = [create(node, toProperties(props, node), node.children)]
     return [SKIP]
   }
+
+  /** @type {import('unist-util-visit').Visitor<Element>} */
+  function substitute(node) {
+    const children = toChildren(content, node)
+    node.children = [create(node, toProperties(props, node), children)]
+    return [SKIP]
+  }
 }
 
 /**

readme.md

@@ -27,6 +27,7 @@
     *   [Example: building content with `hastscript`](#example-building-content-with-hastscript)
     *   [Example: passing content from a string of HTML](#example-passing-content-from-a-string-of-html)
     *   [Example: group](#example-group)
+    *   [Example: behavior substitute](#example-behavior-substitute)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Security](#security)
@@ -162,6 +163,7 @@ Several behaviors are supported:
 *   `'wrap'` — wrap the whole heading text with the link
 *   `'before'` — insert link before the heading
 *   `'after'` — insert link after the heading
+*   `'substitute'` — wrap the `content` with the link
 
 ### `Behavior`
 
@@ -170,7 +172,7 @@ Behavior (TypeScript type).
 ###### Type
 
 ```ts
-type Behavior = 'after' | 'append' | 'before' | 'prepend' | 'wrap'
+type Behavior = 'after' | 'append' | 'before' | 'prepend' | 'wrap' | 'substitute'
 ```
 
 ### `Build`
@@ -356,6 +358,41 @@ Yields:
 <div class="heading-1-group"><a href="#ceres"><span class="icon icon-link"></span></a><h1 id="ceres">Ceres</h1></div>
 ```
 
+### Example: behavior substitute
+
+The following example sets `options.beavior` to `substitute` and passes
+`options.content` as a function, to generate an accessible anchor
+containing the heading text as well as an icon.
+It uses [`hastscript`][hastscript] to build nodes.
+
+```js
+import {h} from 'hastscript'
+import {toString} from 'hast-util-to-string'
+import {rehype} from 'rehype'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
+
+const file = await rehype()
+  .data('settings', {fragment: true})
+  .use(rehypeAutolinkHeadings, {
+    behavior: 'substitute',
+    content(node) {
+      return [
+        h(null, toString(node)),
+        h('span.icon.icon-link', {ariaHidden: 'true'})
+      ]
+    }
+  })
+  .process('<h1 id="substitute">Substitute</h1>')
+
+console.log(String(file))
+```
+
+Yields:
+
+```html
+<h1 id="substitute"><a href="#substitute" tabindex="-1">Substitute<span class="icon icon-link" aria-hidden="true"></span></a></h1>
+```
+
 ## Types
 
 This package is fully typed with [TypeScript][].

test/fixtures/behavior-substitute/config.json

@@ -0,0 +1,17 @@
+{
+  "behavior": "substitute",
+  "content": [
+    {
+      "type": "text",
+      "value": "Bar"
+    },
+    {
+      "type": "element",
+      "tagName": "span",
+      "properties": {
+        "class": "icon icon-link",
+        "aria-hidden": "true"
+      }
+    }
+  ]
+}

test/fixtures/behavior-substitute/input.html

@@ -0,0 +1 @@
+<h1 id="foo">Bar</h1>

test/fixtures/behavior-substitute/output.html

@@ -0,0 +1 @@
+<h1 id="foo"><a tabindex="-1" href="#foo">Bar<span class="icon icon-link" aria-hidden="true"></span></a></h1>