Adding anchor links

package.json

@@ -70,6 +70,7 @@
     "kleur": "^4.1.5",
     "lorem-ipsum": "^2.0.8",
     "markdown-it": "^13.0.1",
+    "markdown-it-anchor": "^8.6.7",
     "markdown-it-attrs": "^4.1.6",
     "markdown-it-deflist": "^2.1.0",
     "netlify-plugin-11ty": "^1.3.0",

source/helpers/components/anchors.ts

@@ -0,0 +1,38 @@
+import Token from 'markdown-it/lib/token';
+import anchor from 'markdown-it-anchor/types';
+
+// Custom permalink function, inspired by and modification of linkInsideHeader
+// More context on custom permalink fns: https://github.com/valeriangalliat/markdown-it-anchor#custom-permalink
+// linkInsideHeader function: https://github.com/valeriangalliat/markdown-it-anchor/blob/649582d58185b00cfb2ceee9b6b4cd6aafc645b7/permalink.js#L76
+export const renderPermalink: anchor.PermalinkGenerator = (
+  slug,
+  opts: anchor.LinkInsideHeaderPermalinkOptions,
+  state,
+  idx,
+) => {
+  opts.ariaHidden = false;
+
+  const title = state?.tokens[idx + 1].children
+    ?.filter(
+      (token: Token) => token.type === 'text' || token.type === 'code_inline',
+    )
+    .reduce((acc, t) => acc + t.content, '');
+
+  const linkTokens = [
+    Object.assign(new state.Token('link_open', 'a', 1), {
+      attrs: [
+        ['class', 'anchor'],
+        ['href', `#${slug}`],
+        ...(opts.ariaHidden ? [['aria-hidden', 'true']] : []),
+      ],
+    }),
+    Object.assign(new state.Token('html_inline', '', 0), {
+      content: `<span class="visuallyhidden">${
+        title ? title : 'section'
+      } permalink'</span>`,
+    }),
+    new state.Token('link_close', 'a', -1),
+  ];
+
+  state?.tokens[idx + 1]?.children?.push(...linkTokens);
+};

source/helpers/engines.ts

@@ -1,9 +1,11 @@
 import { Liquid } from 'liquidjs';
-import markdown from 'markdown-it';
+import markdown, { PluginWithOptions } from 'markdown-it';
 import markdownItAttrs from 'markdown-it-attrs';
 import markdownDefList from 'markdown-it-deflist';
 import path from 'path';
 
+import { renderPermalink } from './components/anchors';
+
 /**
  * Returns Markdown engine with custom configuration and plugins.
  *
@@ -16,7 +18,10 @@ export const markdownEngine = markdown({
   typographer: true,
 })
   .use(markdownDefList)
-  .use(markdownItAttrs);
+  .use(markdownItAttrs)
+  .use(require('markdown-it-anchor') as PluginWithOptions, {
+    permalink: renderPermalink,
+  });
 
 /**
  * Returns LiquidJS engine with custom configuration.

yarn.lock

@@ -5303,6 +5303,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"markdown-it-anchor@npm:^8.6.7":
+  version: 8.6.7
+  resolution: "markdown-it-anchor@npm:8.6.7"
+  peerDependencies:
+    "@types/markdown-it": "*"
+    markdown-it: "*"
+  checksum: 828236768ac7f61ed5591393c1b1bfc5dbf2b6d0c58a3deec606c61dddaa12658a34450cbef37ab50a04453e618ce1efd47d86e4e52595024334898fd306225b
+  languageName: node
+  linkType: hard
+
 "markdown-it-attrs@npm:^4.1.6":
   version: 4.1.6
   resolution: "markdown-it-attrs@npm:4.1.6"
@@ -6758,6 +6768,7 @@ __metadata:
     kleur: ^4.1.5
     lorem-ipsum: ^2.0.8
     markdown-it: ^13.0.1
+    markdown-it-anchor: ^8.6.7
     markdown-it-attrs: ^4.1.6
     markdown-it-deflist: ^2.1.0
     netlify-plugin-11ty: ^1.3.0