Merge pull request sass#37 from oddbird/anchor-links

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,46 @@
+import Token from 'markdown-it/lib/token';
+import type anchor from 'markdown-it-anchor';
+
+/**
+ * Custom permalink function, inspired by `linkInsideHeader`,
+ * modified to include title text in permalink a11y text.
+ * @see https://github.com/valeriangalliat/markdown-it-anchor#custom-permalink
+ * @see https://github.com/valeriangalliat/markdown-it-anchor/blob/649582d58185b00cfb2ceee9b6b4cd6aafc645b7/permalink.js#L76
+ */
+export const renderPermalink: anchor.PermalinkGenerator = (
+  slug,
+  opts: anchor.LinkInsideHeaderPermalinkOptions,
+  state,
+  idx,
+) => {
+  // https://github.com/valeriangalliat/markdown-it-anchor/blob/649582d58185b00cfb2ceee9b6b4cd6aafc645b7/permalink.js#L148-L151
+  const title = state.tokens[idx + 1]?.children
+    ?.filter(
+      (token: Token) => token.type === 'text' || token.type === 'code_inline',
+    )
+    .reduce((acc, t) => acc + t.content, '');
+
+  opts.class = 'anchor';
+  opts.ariaHidden = false;
+  opts.symbol = `<span class="visuallyhidden">${
+    title || 'section'
+  } permalink</span>`;
+
+  // https://github.com/valeriangalliat/markdown-it-anchor/blob/649582d58185b00cfb2ceee9b6b4cd6aafc645b7/permalink.js#L77-L97
+  const linkTokens = [
+    Object.assign(new state.Token('link_open', 'a', 1), {
+      attrs: [
+        ...(opts.class ? [['class', opts.class]] : []),
+        ['href', `#${slug}`],
+        ...(opts.ariaHidden ? [['aria-hidden', 'true']] : []),
+      ],
+    }),
+    Object.assign(new state.Token('html_inline', '', 0), {
+      content: opts.symbol,
+      meta: { isPermalinkSymbol: true },
+    }),
+    new state.Token('link_close', 'a', -1),
+  ];
+
+  state.tokens[idx + 1]?.children?.push(...linkTokens);
+};

source/helpers/engines.ts

@@ -1,9 +1,12 @@
 import { Liquid } from 'liquidjs';
 import markdown from 'markdown-it';
+import markdownAnchor from 'markdown-it-anchor';
 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 +19,11 @@ export const markdownEngine = markdown({
   typographer: true,
 })
   .use(markdownDefList)
-  .use(markdownItAttrs);
+  .use(markdownItAttrs)
+  .use(markdownAnchor, {
+    level: [2],
+    permalink: renderPermalink,
+  });
 
 /**
  * Returns LiquidJS engine with custom configuration.

tsconfig.json

@@ -1,15 +1,12 @@
 {
+  "extends": "ts-node/node16/tsconfig.json",
   "ts-node": {
     "transpileOnly": true
   },
   "compilerOptions": {
-    "module": "node16",
     "target": "es2022",
-    "moduleResolution": "Node16",
-    "strict": true,
-    "esModuleInterop": true,
+    "lib": ["es2022", "DOM"],
     "isolatedModules": true,
-    "forceConsistentCasingInFileNames": true,
     "noEmit": true
   },
   "include": ["source/**/*.ts"],

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