Escape the backslash in markdown link labels

Add the backslash to escapeMd's class, so a title ending in one no longer escapes the `]` that closes its label, and rename it from mdText to pair with escape().
Cover it with synthetic titles parsed back through markdown-it, rather than a corpus title an upstream rename could take away.
Keep stripHtmlComments to a single pass: repeating it would eat the prose a cut splices together, and rawHtmlFindings already reports the leftover.

Signed-off-by: Lu Zhang <lu@wdl.dev>

Author: cnluzhang

scripts/build-content.mjs

@@ -135,7 +135,10 @@ export function summaryOf(md, limit = 155) {
 // code span holding <!-- is documentation that must survive.
 const CODE_OR_COMMENT = /(`+)(?:[^`\n]|\n(?!\s*\n))+\1|<!--[\s\S]*?-->/g;
 
-// Invisible on GitHub, but the renderer escapes them into visible text.
+// Invisible on GitHub, but the renderer escapes them into visible text. One
+// left-to-right pass, deliberately: a cut can splice its neighbours into
+// something comment-shaped (`<!-<!-- -->- x -->`), and a second pass would eat
+// the prose between them. rawHtmlFindings below reports the leftover.
 export const stripHtmlComments = (md) =>
   mapProse(md, (run) => run.replace(CODE_OR_COMMENT, (hit) => (hit.startsWith("<!--") ? "" : hit)));
 

src/index.js

@@ -387,9 +387,9 @@ const estimateTokens = (s) => {
   return Math.ceil((s.length - cjk) / 4 + cjk);
 };
 
-// A title may legitimately contain brackets (see cli/env-overrides), which
-// would otherwise terminate the markdown link early.
-const mdText = (s) => s.replace(/([[\]])/g, "\\$1");
+// Titles become link labels, where an unpaired bracket ends the label early and
+// a trailing backslash escapes the `]` that closes it.
+export const escapeMd = (s) => s.replace(/([\\[\]])/g, "\\$1");
 
 const HOME_MD = [
   "# wdl.md — WDL documentation",
@@ -403,8 +403,8 @@ const HOME_MD = [
     `## ${section}`,
     "",
     ...pages.flatMap((p) => [
-      `- [${mdText(p.en.title)}](${SITE_ORIGIN}/${p.slug}.md)`,
-      ...(p.zh ? [`- [${mdText(p.zh.title)}](${SITE_ORIGIN}/zh/${p.slug}.md) (中文)`] : []),
+      `- [${escapeMd(p.en.title)}](${SITE_ORIGIN}/${p.slug}.md)`,
+      ...(p.zh ? [`- [${escapeMd(p.zh.title)}](${SITE_ORIGIN}/zh/${p.slug}.md) (中文)`] : []),
     ]),
     "",
   ]),

test/build-content.test.js

@@ -52,6 +52,10 @@ test("stripHtmlComments drops comments from prose, never from code", () => {
   assert.ok(stripHtmlComments("use `<!-- x -->` here").includes("`<!-- x -->`"));
 });
 
+test("a cut that splices a new comment must not eat the prose", () => {
+  assert.ok(stripHtmlComments("<!-<!-- -->- x -->").includes("x"));
+});
+
 test("a comment after an unmatched backtick is still stripped", () => {
   // The code-span guard must not span a blank line, or the comment hides inside
   // a fake span and renders as visible escaped text.

test/worker.test.js

@@ -4,7 +4,8 @@
 // markdown.test.js, and the agent contract in agents-md.test.js.
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import worker from "../src/index.js";
+import MarkdownIt from "markdown-it";
+import worker, { escapeMd } from "../src/index.js";
 import { PAGES } from "../src/content.gen.js";
 
 const get = (path, headers = {}) =>
@@ -97,13 +98,25 @@ test("sitemap.xml lists home plus every en and zh page", async () => {
   // an untranslated page carries none.
   const bilingual = PAGES.find((p) => p.zh).slug;
   const solo = PAGES.find((p) => !p.zh).slug;
-  const entry = (loc) =>
-    body.match(new RegExp(`<url>\\s*<loc>${loc.replace(/[/.]/g, "\\$&")}</loc>[^]*?</url>`))[0];
+  // Split rather than build a regex out of a slug, which would need escaping.
+  const entry = (loc) => body.split("</url>").find((b) => b.includes(`<loc>${loc}</loc>`));
   assert.ok(entry(`https://wdl.md/${bilingual}`).includes(`hreflang="zh" href="https://wdl.md/zh/${bilingual}"`));
   assert.ok(entry(`https://wdl.md/zh/${bilingual}`).includes(`hreflang="x-default" href="https://wdl.md/${bilingual}"`));
   assert.ok(!entry(`https://wdl.md/${solo}`).includes("xhtml:link"));
 });
 
+test("any upstream title survives as a link label in the markdown index", () => {
+  // Synthetic on purpose: an upstream rename must not decide what this covers.
+  // The trailing backslash is the shape that breaks; CommonMark pairs brackets.
+  const md = new MarkdownIt();
+  for (const title of ["plain", "balanced [b] here", "unpaired [ here", "trailing \\"]) {
+    assert.equal(
+      md.renderInline(`[${escapeMd(title)}](${SITE}x.md)`),
+      `<a href="${SITE}x.md">${title}</a>`,
+    );
+  }
+});
+
 test("llms.txt indexes every page in both languages", async () => {
   const res = await get("/llms.txt");
   assert.equal(res.headers.get("content-type"), "text/plain; charset=utf-8");