fix broken links, and validate

Author: mbostock

docs/components/links.js

@@ -0,0 +1,45 @@
+import {readdir, readFile, stat} from "fs/promises";
+
+// Anchors can be derived from headers, or explicitly written as {#names}.
+export function getAnchors(text) {
+  const anchors = [];
+  for (const [, header] of text.matchAll(/^#+ ([*\w][*().,\w\d -]+)\n/gm)) {
+    anchors.push(
+      header
+        .replaceAll(/[^\w\d\s]+/g, " ")
+        .trim()
+        .replaceAll(/ +/g, "-")
+        .toLowerCase()
+    );
+  }
+  for (const [, anchor] of text.matchAll(/ \{#([\w\d-]+)\}/g)) {
+    anchors.push(anchor);
+  }
+  return anchors;
+}
+
+// Internal links.
+export function getLinks(file, text) {
+  const links = [];
+  for (const match of text.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
+    const [, link] = match;
+    if (/^\w+:/.test(link)) continue; // absolute link with protocol
+    const {pathname, hash} = new URL(link, new URL(file, "https://example.com/"));
+    links.push({pathname, hash});
+  }
+  return links;
+}
+
+// In source files, ignore comments.
+export async function readMarkdownSource(f) {
+  return (await readFile(f, "utf8")).replaceAll(/<!-- .*? -->/gs, "");
+}
+
+// Recursively find all md files in the directory.
+export async function* readMarkdownFiles(root, subpath = "/") {
+  for (const fname of await readdir(root + subpath)) {
+    if (fname.startsWith(".") || fname.endsWith(".js")) continue; // ignore .vitepress etc.
+    if ((await stat(root + subpath + fname)).isDirectory()) yield* readMarkdownFiles(root, subpath + fname + "/");
+    else if (fname.endsWith(".md")) yield subpath + fname;
+  }
+}

docs/data/api.data.ts

@@ -1,5 +1,6 @@
 import {rollup, sort} from "d3";
 import {FunctionDeclaration, Node, Project, VariableStatement} from "ts-morph";
+import {readMarkdownFiles, readMarkdownSource, getAnchors} from "../components/links.js";
 
 // These interfaces tend to represent things that Plot constructs internally,
 // rather than objects that the user is expected to provide.
@@ -43,8 +44,12 @@ function getHref(name: string, path: string): string {
     case "features/curve":
     case "features/format":
     case "features/mark":
+    case "features/marker":
     case "features/plot":
+    case "features/projection":
       return `${path}s`;
+    case "features/inset":
+      return "features/scales";
     case "features/options":
       return "features/transforms";
     case "marks/axis": {
@@ -88,6 +93,7 @@ function getInterfaceName(name: string, path: string): string {
 export default {
   watch: [],
   async load() {
+    // Parse the TypeScript declarations to get exported symbols.
     const project = new Project({tsConfigFilePath: "tsconfig.json"});
     const allMethods: {name: string; comment: string; href: string}[] = [];
     const allOptions: {name: string; context: {name: string; href: string}}[] = [];
@@ -117,6 +123,27 @@ export default {
         }
       }
     }
+    // Parse the Markdown files to get all known anchors.
+    const root = "docs";
+    const anchors = new Map();
+    for await (const file of readMarkdownFiles(root)) {
+      const text = await readMarkdownSource(root + file);
+      anchors.set(file, getAnchors(text));
+    }
+    // Cross-reference the generated links.
+    for (const {name, href} of allMethods) {
+      if (!anchors.has(`/${href}.md`)) {
+        throw new Error(`file not found: ${href}`);
+      }
+      if (!anchors.get(`/${href}.md`).includes(name)) {
+        throw new Error(`anchor not found: ${href}#${name}`);
+      }
+    }
+    for (const {context: {href}} of allOptions) {
+      if (!anchors.has(`/${href}.md`)) {
+        throw new Error(`file not found: ${href}`);
+      }
+    }
     return {
       methods: sort(allMethods, ({name}) => name),
       options: sort(

test/docs-test.js

@@ -1,5 +1,5 @@
 import assert from "assert";
-import {readdir, readFile, stat} from "fs/promises";
+import {readMarkdownFiles, readMarkdownSource, getAnchors, getLinks} from "../docs/components/links.js";
 
 it("documentation links point to existing internal anchors", async () => {
   const root = "docs";
@@ -28,47 +28,3 @@ it("documentation links point to existing internal anchors", async () => {
   }
   assert(errors.length === 0, new Error(`${errors.length} broken links:\n${errors.join("\n")}`));
 });
-
-// Anchors can be derived from headers, or explicitly written as {#names}.
-function getAnchors(text) {
-  const anchors = [];
-  for (const [, header] of text.matchAll(/^#+ ([*\w][*().,\w\d -]+)\n/gm)) {
-    anchors.push(
-      header
-        .replaceAll(/[^\w\d\s]+/g, " ")
-        .trim()
-        .replaceAll(/ +/g, "-")
-        .toLowerCase()
-    );
-  }
-  for (const [, anchor] of text.matchAll(/ \{#([\w\d-]+)\}/g)) {
-    anchors.push(anchor);
-  }
-  return anchors;
-}
-
-// Internal links.
-function getLinks(file, text) {
-  const links = [];
-  for (const match of text.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
-    const [, link] = match;
-    if (/^\w+:/.test(link)) continue; // absolute link with protocol
-    const {pathname, hash} = new URL(link, new URL(file, "https://example.com/"));
-    links.push({pathname, hash});
-  }
-  return links;
-}
-
-// In source files, ignore comments.
-async function readMarkdownSource(f) {
-  return (await readFile(f, "utf8")).replaceAll(/<!-- .*? -->/gs, "");
-}
-
-// Recursively find all md files in the directory.
-async function* readMarkdownFiles(root, subpath = "/") {
-  for (const fname of await readdir(root + subpath)) {
-    if (fname.startsWith(".") || fname.endsWith(".js")) continue; // ignore .vitepress etc.
-    if ((await stat(root + subpath + fname)).isDirectory()) yield* readMarkdownFiles(root, subpath + fname + "/");
-    else if (fname.endsWith(".md")) yield subpath + fname;
-  }
-}