Add markdown syntax for section links

Author: jdesrosiers

build/build.js

@@ -7,9 +7,12 @@ import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
 import remarkFlexibleContainers from "remark-flexible-containers";
 import remarkGfm from "remark-gfm";
+import remarkHeadingId from "remark-heading-id";
+import remarkHeadings from "@vcarl/remark-headings";
 import remarkNumberHeadings from "./remark-number-headings.js";
 import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
 import remarkRehype from "remark-rehype";
+import remarkSectionLinks from "./remark-section-links.js";
 import remarkToc from "remark-toc";
 import remarkValidateLinks from "remark-validate-links";
 import torchLight from "remark-torchlight";
@@ -24,12 +27,15 @@ dotenv.config();
     .use(remarkGfm)
     .use(torchLight)
     .use(remarkFlexibleContainers)
+    .use(remarkHeadingId)
     .use(remarkNumberHeadings, {
       startDepth: 2,
       skip: ["Abstract", "Note to Readers", "Table of Contents", "Authors' Addresses", "\\[.*\\]", "draft-.*"],
       appendixToken: "[Appendix]",
       appendixPrefix: "Appendix"
     })
+    .use(remarkHeadings)
+    .use(remarkSectionLinks)
     .use(remarkToc, {
       tight: true,
       heading: "Table of Contents",

build/remark-section-links.js

@@ -0,0 +1,43 @@
+import { visit } from "unist-util-visit";
+
+
+const sectionLink = /\{\{(?<id>.*?)\}\}/u;
+
+const remarkSectionLinks = (options) => (tree, vfile) => {
+  // Heading data comes from @vcarl/remark-headings
+  const headings = {};
+  for (const heading of vfile.data.headings) {
+    if (heading?.data?.id) {
+      headings[heading.data.id] = heading.value;
+    }
+  }
+
+  visit(tree, "text", (node, index, parent) => {
+    const match = node.value.match(sectionLink);
+
+    if (match) {
+      if (!(match.groups.id in headings)) {
+        throw Error(`SectionLinkError: No header found with id "${match.groups.id}"`)
+      }
+      const headerText = headings[match.groups.id];
+
+      const beforeNode = { type: "text", value: node.value.slice(0, match.index) };
+      const afterNode = { type: "text", value: node.value.slice(match.index + match[0].length) };
+      const linkNode = {
+        type: "link",
+        title: headerText,
+        url: `#${match.groups.id}`,
+        children: [
+          {
+            type: "text",
+            value: "Section " + headerText.slice(0, headerText.indexOf(". "))
+          }
+        ]
+      };
+
+      parent.children.splice(index, 1, beforeNode, linkNode, afterNode);
+    }
+  });
+};
+
+export default remarkSectionLinks;