feat(gatsby-remark-autolink-headers): Support {#custom-id} header syntax (#14253)

- add enableCustomId option
- enable usage of custom-id ``{#custom-id}` when enableCustomId  is set to true

Author: yunabe

packages/gatsby-remark-autolink-headers/README.md

@@ -57,6 +57,7 @@ Note: if you are using `gatsby-remark-prismjs`, make sure that it’s listed aft
 - `className`: String. Set your own class for the anchor (optional)
 - `maintainCase`: Boolean. Maintains the case for markdown header (optional)
 - `removeAccents`: Boolean. Remove accents from generated headings IDs (optional)
+- `enableCustomId`: Boolean. Enable custom header IDs with `{#id}` (optional)
 
 ```javascript
 // In your gatsby-config.js

packages/gatsby-remark-autolink-headers/src/__tests__/index.js

@@ -1,4 +1,5 @@
 const Remark = require(`remark`)
+const toString = require(`mdast-util-to-string`)
 const visit = require(`unist-util-visit`)
 
 const plugin = require(`../`)
@@ -182,4 +183,60 @@ describe(`gatsby-remark-autolink-headers`, () => {
       expect(node.data.id).toEqual(expect.stringMatching(/^heading/))
     })
   })
+
+  it(`extracts custom id`, () => {
+    const markdownAST = remark.parse(`
+# Heading One {#custom_h1}
+
+## Heading Two {#custom-heading-two}
+
+# With *Bold* {#custom-withbold}
+
+# Invalid {#this_is_italic}
+
+# No custom ID
+
+# {#id-only}
+
+# {#text-after} custom ID
+    `)
+    const enableCustomId = true
+
+    const transformed = plugin({ markdownAST }, { enableCustomId })
+
+    const headers = []
+    visit(transformed, `heading`, node => {
+      headers.push({ text: toString(node), id: node.data.id })
+    })
+    expect(headers).toEqual([
+      {
+        id: `custom_h1`,
+        text: `Heading One`,
+      },
+      {
+        id: `custom-heading-two`,
+        text: `Heading Two`,
+      },
+      {
+        id: `custom-withbold`,
+        text: `With Bold`,
+      },
+      {
+        id: `invalid-thisisitalic`,
+        text: `Invalid {#thisisitalic}`,
+      },
+      {
+        id: `no-custom-id`,
+        text: `No custom ID`,
+      },
+      {
+        id: `id-only`,
+        text: `{#id-only}`,
+      },
+      {
+        id: `text-after-custom-id`,
+        text: `{#text-after} custom ID`,
+      },
+    ])
+  })
 })

packages/gatsby-remark-autolink-headers/src/index.js

@@ -20,13 +20,32 @@ module.exports = (
     className = `anchor`,
     maintainCase = false,
     removeAccents = false,
+    enableCustomId = false,
   }
 ) => {
   slugs.reset()
 
   visit(markdownAST, `heading`, node => {
-    const slug = slugs.slug(toString(node), maintainCase)
-    const id = removeAccents ? deburr(slug) : slug
+    let id
+    if (enableCustomId && node.children.length > 0) {
+      const last = node.children[node.children.length - 1]
+      // This regex matches to preceding spaces and {#custom-id} at the end of a string.
+      // Also, checks the text of node won't be empty after the removal of {#custom-id}.
+      const match = /^(.*?)\s*\{#([\w-]+)\}$/.exec(toString(last))
+      if (match && (match[1] || node.children.length > 1)) {
+        id = match[2]
+        // Remove the custom ID from the original text.
+        if (match[1]) {
+          last.value = match[1]
+        } else {
+          node.children.pop()
+        }
+      }
+    }
+    if (!id) {
+      const slug = slugs.slug(toString(node), maintainCase)
+      id = removeAccents ? deburr(slug) : slug
+    }
     const data = patch(node, `data`, {})
 
     patch(data, `id`, id)