91 lines
3.2 KiB
JavaScript
91 lines
3.2 KiB
JavaScript
/*
|
|
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, "") // <code>, <em>, <a> … 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 };
|