add tests, fix options format, add documentation

Author: jescalan

README.md

@@ -46,10 +46,12 @@ const mdx = require('@mdx-js/mdx')
 const {allPlugins} = require('@hashicorp/remark-plugins')
 
 console.log(mdx.sync('some markdown content', {
-  remarkPlugins: allPlugins
+  remarkPlugins: allPlugins(/* options */)
 })
 ```
 
+Plugin options can be passed to `allPlugins` as an object, with the keys being plugin names. For example, to pass options to `headingLinkable`, you could call `allPlugins({ headingLinkable: { foo: 'bar' } })`.
+
 If you are using `next-hashicorp`, all of these plugins will be included by default.
 
 ## Publishing

index.js

@@ -14,9 +14,11 @@ module.exports = {
 }
 
 // for easy use of everything at the same time
-module.exports.allPlugins = ({ headingLinkable } = {}) => [
+module.exports.allPlugins = ({
+  headingLinkable: headingLinkableOptions
+} = {}) => [
   includeMarkdown,
-  headingLinkable(headingLinkable),
+  [headingLinkable, headingLinkableOptions],
   inlineCodeLinkable,
   paragraphCustomAlerts,
   typography

index.test.js

@@ -6,5 +6,7 @@ it('api works as intended', () => {
   expect(remarkPlugins.paragraphCustomAlerts).toBeTruthy()
   expect(remarkPlugins.typography).toBeTruthy()
   expect(remarkPlugins.includeMarkdown).toBeTruthy()
-  expect(remarkPlugins.allPlugins.length).toBe(5)
+  expect(remarkPlugins.allPlugins().length).toBe(5)
+  // passes options to headingLinkable correctly
+  expect(remarkPlugins.allPlugins({ headingLinkable: 'foo' })[1][1]).toBe('foo')
 })

plugins/heading-linkable/README.md

@@ -41,3 +41,9 @@ Content here...
 ```
 
 Since the `__target` element actually carries the id rather than the headline, it can be positioned independently to pad the headline off the top of the page if necessary, which is the case any time we use a "sticky" navigation.
+
+## Options
+
+- `compatibilitySlug` _(optional)_ - if present, will generate an additional target element using a custom slug creation algorithm. Accepts a function with the following signature `fn(text: string)`. The `text` argument is the headline text, if the `compatibilitySlug` function generates an idential slug as the default, it will not be added at all.
+
+  > **NOTE:** Be conscious of duplicate tracking with your compatibility function. If it needs to keep track of existing slugs on the page to avoid duplicates, it must implement that functionality on its own. Default slugs are not exposed to the `compatibilitySlug` function because this offers a footgun that can easily break compatibility. The `compatibilitySlug` function should operate entirely in its own sphere -- if it happens to generate a duplicate slug, the plugin itself will remove it as compatibility isn't necessary in that instance.

plugins/heading-linkable/index.js

@@ -19,11 +19,13 @@ module.exports = function headingLinkablePlugin({ compatibilitySlug } = {}) {
       })
 
       if (compatibilitySlug) {
-        const slug2 = compatibilitySlug(text, links)
-        node.children.unshift({
-          type: 'html',
-          value: `<a class="__target_compat" id="${slug2}" aria-hidden="true"></a>`
-        })
+        const slug2 = compatibilitySlug(text)
+        if (slug !== slug2) {
+          node.children.unshift({
+            type: 'html',
+            value: `<a class="__target_compat" id="${slug2}" aria-hidden="true"></a>`
+          })
+        }
       }
 
       node.children.unshift({

plugins/heading-linkable/index.test.js

@@ -11,7 +11,13 @@ describe('heading-linkable', () => {
         .processSync('# hello world')
         .toString()
     ).toMatch(
-      '<h1><a class="anchor" href="#hello-world" aria-label="hello world permalink">»</a><a class="__target" id="hello-world" aria-hidden="true"></a>hello world</h1>'
+      [
+        '<h1>',
+        '<a class="anchor" href="#hello-world" aria-label="hello world permalink">»</a>',
+        '<a class="__target" id="hello-world" aria-hidden="true"></a>',
+        'hello world',
+        '</h1>'
+      ].join('')
     )
   })
 
@@ -106,7 +112,32 @@ describe('heading-linkable', () => {
         .processSync('# hello world')
         .toString()
     ).toMatch(
-      '<h1><a class="anchor" href="#hello-world" aria-label="hello world permalink">»</a><a class="__target_compat" id="foo" aria-hidden="true"></a><a class="__target" id="hello-world" aria-hidden="true"></a>hello world</h1>'
+      [
+        '<h1>',
+        '<a class="anchor" href="#hello-world" aria-label="hello world permalink">»</a>',
+        '<a class="__target_compat" id="foo" aria-hidden="true"></a>',
+        '<a class="__target" id="hello-world" aria-hidden="true"></a>',
+        'hello world',
+        '</h1>'
+      ].join('')
+    )
+  })
+
+  test('does not render duplicate compatibility slugs', () => {
+    expect(
+      remark()
+        .use(headingLinkable, { compatibilitySlug: slug => 'hello-world' })
+        .use(html)
+        .processSync('# hello world')
+        .toString()
+    ).toMatch(
+      [
+        '<h1>',
+        '<a class="anchor" href="#hello-world" aria-label="hello world permalink">»</a>',
+        '<a class="__target" id="hello-world" aria-hidden="true"></a>',
+        'hello world',
+        '</h1>'
+      ].join('')
     )
   })
 })