/* String helpers for the documentation under /docs: the words a heading shows, the anchor it gets, and the headings the sidebar lists. They import nothing at all, not even marked, because the repository root installs no dependencies and `tests/docs.test.js` loads this file straight from source. */ // What marked escapes, back to the character it stands for: an anchor has to be the same whether it // was written as `'` or arrived as `'`. const Entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", "#39": "'", "#x27": "'", }; function DecodeEntities(value) { return value.replace(/&(#?[a-z0-9]+);/gi, (entity, body) => (Entities[body.toLowerCase()] ?? "")); } // A heading's anchor is built from its markdown source when the sidebar is built, and from the HTML // marked has rendered when the page is. This drops everything the two forms disagree on — the tags // marked adds, the entities it escapes, and the characters markdown uses for emphasis and links — so // both keep the same words and land on the same anchor. function HeadingText(value) { return DecodeEntities( String(value ?? "") .replace(/<[^>]*>/g, "") // , , … around the heading's words .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1") // a link keeps the label it shows, not its target .replace(/[*_`~]/g, "") // emphasis ).trim(); } // Lower case letters, numbers and dashes: what a url fragment and a query selector both accept. function Slugify(value) { return HeadingText(value) .toLowerCase() .replace(/[^a-z0-9]+/g, "-") .replace(/^-+|-+$/g, ""); } // Two headings with the same words cannot share an anchor: the second becomes `words-1`, the third // `words-2`. The sidebar and the renderer both walk a page's headings in document order, so the // numbers they hand out are the same. function CreateHeadingSlugger() { const seen = new Map(); return (value) => { const base = Slugify(value) || "section"; const times = seen.get(base) || 0; seen.set(base, times + 1); return times === 0 ? base : `${base}-${times}`; }; } // The headings of a markdown document, in order, each with the anchor its renderer will give it: // `{ depth: 2, text: "Link a world", slug: "link-a-world" }`. Lines inside a fenced code block are // skipped — a `# comment` there is shell, not a heading. function HeadingsFromMarkdown(source) { const slug = CreateHeadingSlugger(); const headings = []; let inFence = false; for (const line of String(source ?? "").split(/\r?\n/)) { if (/^ {0,3}(```|~~~)/.test(line)) { inFence = !inFence; continue; } if (inFence) continue; const heading = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line); if (!heading) continue; const text = HeadingText(heading[2]); headings.push({ depth: heading[1].length, text, slug: slug(text) }); } return headings; } // A documentation page's title is its first heading. function TitleFromMarkdown(source) { const [first] = HeadingsFromMarkdown(source); return first ? first.text : ""; } export { CreateHeadingSlugger, HeadingsFromMarkdown, HeadingText, Slugify, TitleFromMarkdown };