feat(gatsby-remark-autolink-headers): Optionally specify header element types (#23366)

* Add elements prop to options that enables anchor generation for specified header tags only

* Update README to reflect addition of elements option

* Do not return markdownAST from node callback function in gatsby-remark-autolink-headers

* Fix Prettier format issues in gatsby-recipes README

Author: jmadelaine

packages/gatsby-recipes/README.md

@@ -199,7 +199,7 @@ a step
 
 But this won't
 
-<!-- prettier-ignore -->
+<!-- prettier-ignore-start -->
 ```mdx
 # Recipes
 ---
@@ -208,6 +208,7 @@ a step
 
 <File src="something.txt" content="something" />
 ```
+<!-- prettier-ignore-end -->
 
 ### Q) What kind of recipe should I write?
 

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

@@ -59,6 +59,7 @@ Note: if you are using `gatsby-remark-prismjs`, make sure that it’s listed aft
 - `removeAccents`: Boolean. Remove accents from generated headings IDs (optional)
 - `enableCustomId`: Boolean. Enable custom header IDs with `{#id}` (optional)
 - `isIconAfterHeader`: Boolean. Enable the anchor icon to be inline at the end of the header text (optional)
+- `elements`: String array. Specify which type of header tags to link (optional)
 
 ```javascript
 // In your gatsby-config.js
@@ -77,6 +78,7 @@ module.exports = {
               maintainCase: true,
               removeAccents: true,
               isIconAfterHeader: true,
+              elements: [`h1`, `h4`],
             },
           },
         ],

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

@@ -250,6 +250,73 @@ Object {
 }
 `;
 
+exports[`gatsby-remark-autolink-headers adds id to a markdown heading when elements prop is passed with matching heading type 1`] = `
+Object {
+  "children": Array [
+    Object {
+      "children": Array [],
+      "data": Object {
+        "hChildren": Array [
+          Object {
+            "type": "raw",
+            "value": "<svg aria-hidden=\\"true\\" focusable=\\"false\\" height=\\"16\\" version=\\"1.1\\" viewBox=\\"0 0 16 16\\" width=\\"16\\"><path fill-rule=\\"evenodd\\" d=\\"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z\\"></path></svg>",
+          },
+        ],
+        "hProperties": Object {
+          "aria-label": "heading uno permalink",
+          "class": "anchor before",
+        },
+      },
+      "title": null,
+      "type": "link",
+      "url": "#heading-uno",
+    },
+    Object {
+      "position": Position {
+        "end": Object {
+          "column": 14,
+          "line": 1,
+          "offset": 13,
+        },
+        "indent": Array [],
+        "start": Object {
+          "column": 3,
+          "line": 1,
+          "offset": 2,
+        },
+      },
+      "type": "text",
+      "value": "Heading Uno",
+    },
+  ],
+  "data": Object {
+    "hProperties": Object {
+      "id": "heading-uno",
+      "style": "position:relative;",
+    },
+    "htmlAttributes": Object {
+      "id": "heading-uno",
+    },
+    "id": "heading-uno",
+  },
+  "depth": 1,
+  "position": Position {
+    "end": Object {
+      "column": 14,
+      "line": 1,
+      "offset": 13,
+    },
+    "indent": Array [],
+    "start": Object {
+      "column": 1,
+      "line": 1,
+      "offset": 0,
+    },
+  },
+  "type": "heading",
+}
+`;
+
 exports[`gatsby-remark-autolink-headers adds places anchor after header when isIconAfterHeader prop is passed 1`] = `
 Object {
   "children": Array [
@@ -317,6 +384,84 @@ Object {
 }
 `;
 
+exports[`gatsby-remark-autolink-headers does not add data to a markdown heading when elements prop is passed with no matching heading type 1`] = `
+Object {
+  "children": Array [
+    Object {
+      "position": Position {
+        "end": Object {
+          "column": 14,
+          "line": 1,
+          "offset": 13,
+        },
+        "indent": Array [],
+        "start": Object {
+          "column": 3,
+          "line": 1,
+          "offset": 2,
+        },
+      },
+      "type": "text",
+      "value": "Heading Uno",
+    },
+  ],
+  "depth": 1,
+  "position": Position {
+    "end": Object {
+      "column": 14,
+      "line": 1,
+      "offset": 13,
+    },
+    "indent": Array [],
+    "start": Object {
+      "column": 1,
+      "line": 1,
+      "offset": 0,
+    },
+  },
+  "type": "heading",
+}
+`;
+
+exports[`gatsby-remark-autolink-headers does not add data to a markdown heading with custom id when elements prop is passed with no matching heading type 1`] = `
+Object {
+  "children": Array [
+    Object {
+      "position": Position {
+        "end": Object {
+          "column": 27,
+          "line": 1,
+          "offset": 26,
+        },
+        "indent": Array [],
+        "start": Object {
+          "column": 3,
+          "line": 1,
+          "offset": 2,
+        },
+      },
+      "type": "text",
+      "value": "Heading Uno {#custom_h1}",
+    },
+  ],
+  "depth": 1,
+  "position": Position {
+    "end": Object {
+      "column": 27,
+      "line": 1,
+      "offset": 26,
+    },
+    "indent": Array [],
+    "start": Object {
+      "column": 1,
+      "line": 1,
+      "offset": 0,
+    },
+  },
+  "type": "heading",
+}
+`;
+
 exports[`gatsby-remark-autolink-headers maintain case of markdown header for id 1`] = `
 Object {
   "children": Array [

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

@@ -239,6 +239,7 @@ describe(`gatsby-remark-autolink-headers`, () => {
       },
     ])
   })
+
   it(`adds places anchor after header when isIconAfterHeader prop is passed`, () => {
     const markdownAST = remark.parse(`# Heading Uno`)
 
@@ -253,4 +254,101 @@ describe(`gatsby-remark-autolink-headers`, () => {
       expect(node).toMatchSnapshot()
     })
   })
+
+  it(`adds id to a markdown heading when elements prop is passed with matching heading type`, () => {
+    const markdownAST = remark.parse(`# Heading Uno`)
+
+    const transformed = plugin({ markdownAST }, { elements: [`h1`] })
+
+    visit(transformed, `heading`, node => {
+      expect(node.data.id).toBeDefined()
+
+      expect(node).toMatchSnapshot()
+    })
+  })
+
+  it(`does not add data to a markdown heading when elements prop is passed with no matching heading type`, () => {
+    const markdownAST = remark.parse(`# Heading Uno`)
+
+    const transformed = plugin({ markdownAST }, { elements: [`h2`] })
+
+    visit(transformed, `heading`, node => {
+      expect(node.data).not.toBeDefined()
+
+      expect(node).toMatchSnapshot()
+    })
+  })
+
+  it(`does not add data to a markdown heading with custom id when elements prop is passed with no matching heading type`, () => {
+    const markdownAST = remark.parse(`# Heading Uno {#custom_h1}`)
+
+    const transformed = plugin({ markdownAST }, { elements: [`h2`] })
+
+    visit(transformed, `heading`, node => {
+      expect(node.data).not.toBeDefined()
+
+      expect(node).toMatchSnapshot()
+    })
+  })
+
+  it(`only adds ids to markdown headings whose heading type is included in the passed elements prop`, () => {
+    const markdownAST = remark.parse(`
+    # Heading One
+  
+    ## Heading Two
+  
+    ### Heading Three
+        `)
+
+    const transformed = plugin({ markdownAST }, { elements: [`h2`] })
+
+    visit(transformed, `heading`, node => {
+      if (node.depth === 2) {
+        expect(node.data.id).toBeDefined()
+      } else {
+        expect(node.data).not.toBeDefined()
+      }
+    })
+  })
+
+  it(`does not add data to markdown headings when an empty array elements prop is passed`, () => {
+    const markdownAST = remark.parse(`
+    # Heading One
+  
+    ## Heading Two
+  
+    ### Heading Three
+        `)
+
+    const transformed = plugin({ markdownAST }, { elements: [] })
+
+    visit(transformed, `heading`, node => {
+      expect(node.data).not.toBeDefined()
+    })
+  })
+
+  it(`allows all six heading depths to be passed in the elements prop`, () => {
+    const markdownAST = remark.parse(`
+    # Heading One
+  
+    ## Heading Two
+  
+    ### Heading Three
+
+    #### Heading Four
+  
+    ##### Heading Five
+  
+    ###### Heading Six
+        `)
+
+    const transformed = plugin(
+      { markdownAST },
+      { elements: [`h1`, `h2`, `h3`, `h4`, `h5`, `h6`] }
+    )
+
+    visit(transformed, `heading`, node => {
+      expect(node.data.id).toBeDefined()
+    })
+  })
 })

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

@@ -22,11 +22,17 @@ module.exports = (
     removeAccents = false,
     enableCustomId = false,
     isIconAfterHeader = false,
+    elements = null,
   }
 ) => {
   slugs.reset()
 
   visit(markdownAST, `heading`, node => {
+    // If elements array exists, do not create links for heading types not included in array
+    if (Array.isArray(elements) && !elements.includes(`h${node.depth}`)) {
+      return
+    }
+
     let id
     if (enableCustomId && node.children.length > 0) {
       const last = node.children[node.children.length - 1]