Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s
All checks were successful
Test / test (push) Successful in 2s
This commit is contained in:
114
frontend/app/services/Docs.js
Normal file
114
frontend/app/services/Docs.js
Normal file
@@ -0,0 +1,114 @@
|
||||
import { Marked } from "marked";
|
||||
import { CreateHeadingSlugger, HeadingsFromMarkdown, TitleFromMarkdown } from "./DocsMarkdown";
|
||||
|
||||
/*
|
||||
The documentation served at /docs is markdown files under app/content/docs, so writing a page means
|
||||
adding a file. The layout of a page's path says everything the sidebar needs:
|
||||
|
||||
app/content/docs/<group>/<NN>-<page>.md
|
||||
|
||||
The folder is the sidebar group and its own number orders the groups, the number in front of the file
|
||||
orders the pages inside its group, and the rest of the file name is the page's slug (`02-discord.md`
|
||||
is `/docs/discord`). A page's title is its first heading, and the first page of the first group is
|
||||
served at `/docs` itself.
|
||||
|
||||
A group's label is looked up under `docs.groups.<folder>` in the locale files of
|
||||
`i18n/locales/en/docs.json` and its siblings, so a new group needs that label in every locale.
|
||||
*/
|
||||
const markdownFiles = import.meta.glob("../content/docs/*/*.md", { query: "?raw", eager: true, import: "default" });
|
||||
|
||||
const Numbered = /^(\d+)-/;
|
||||
const WithoutNumber = (name) => name.replace(Numbered, "");
|
||||
// A name without a number in front sorts after every numbered one in its folder.
|
||||
const OrderOf = (name) => {
|
||||
const numbered = Numbered.exec(name);
|
||||
return numbered ? Number(numbered[1]) : Number.MAX_SAFE_INTEGER;
|
||||
};
|
||||
|
||||
const pages = Object.entries(markdownFiles)
|
||||
.map(([file, source]) => {
|
||||
const [folder, filename] = file.split("/").slice(-2);
|
||||
const markdown = String(source ?? "");
|
||||
|
||||
return {
|
||||
group: WithoutNumber(folder),
|
||||
groupOrder: OrderOf(folder),
|
||||
slug: WithoutNumber(filename).replace(/\.md$/, ""),
|
||||
order: OrderOf(filename),
|
||||
title: TitleFromMarkdown(markdown),
|
||||
headings: HeadingsFromMarkdown(markdown),
|
||||
markdown,
|
||||
};
|
||||
})
|
||||
.sort((left, right) =>
|
||||
left.groupOrder - right.groupOrder || left.order - right.order || left.slug.localeCompare(right.slug)
|
||||
);
|
||||
|
||||
// `/docs` is the first page of the documentation, the rest hang under it by their slug.
|
||||
function GetDocsHref(slug) {
|
||||
return pages.length && slug === pages[0].slug ? "/docs" : `/docs/${slug}`;
|
||||
}
|
||||
|
||||
function GetDocsFirstSlug() {
|
||||
return pages.length ? pages[0].slug : "";
|
||||
}
|
||||
|
||||
// The sidebar: one entry per group folder, in reading order, holding its pages.
|
||||
function GetDocsNav() {
|
||||
const nav = [];
|
||||
|
||||
for (const page of pages) {
|
||||
let group = nav.find((entry) => entry.key === page.group);
|
||||
if (!group) {
|
||||
group = { key: page.group, pages: [] };
|
||||
nav.push(group);
|
||||
}
|
||||
group.pages.push({ slug: page.slug, title: page.title, href: GetDocsHref(page.slug) });
|
||||
}
|
||||
|
||||
return nav;
|
||||
}
|
||||
|
||||
const marked = new Marked();
|
||||
|
||||
// Every heading gets the anchor the sidebar and the "on this page" list link to. The slugger is
|
||||
// replaced at the start of a parse so each page numbers its repeated headings on its own: marked
|
||||
// parses one document at a time and does it synchronously, so no other parse can cut in.
|
||||
let slugHeadings = CreateHeadingSlugger();
|
||||
|
||||
marked.use({
|
||||
renderer: {
|
||||
heading({ tokens, depth }) {
|
||||
const content = this.parser.parseInline(tokens);
|
||||
return `<h${depth} id="${slugHeadings(content)}">${content}</h${depth}>`;
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
function RenderDocsMarkdown(markdown) {
|
||||
slugHeadings = CreateHeadingSlugger();
|
||||
return String(marked.parse(markdown || ""));
|
||||
}
|
||||
|
||||
// What the /docs page shows: a rendered page with the headings it holds and whichever pages come
|
||||
// before and after it, or null when nothing is published under that slug.
|
||||
function GetDocsPage(slug) {
|
||||
const index = pages.findIndex((page) => page.slug === slug);
|
||||
if (index === -1) return null;
|
||||
|
||||
const page = pages[index];
|
||||
const neighbours = (page) => (page ? { slug: page.slug, title: page.title, href: GetDocsHref(page.slug) } : null);
|
||||
|
||||
return {
|
||||
slug: page.slug,
|
||||
group: page.group,
|
||||
title: page.title,
|
||||
// The page's own h1 is in the body already; the list is for its sections.
|
||||
headings: page.headings.filter((heading) => heading.depth > 1 && heading.depth <= 3),
|
||||
html: RenderDocsMarkdown(page.markdown),
|
||||
previous: neighbours(pages[index - 1]),
|
||||
next: neighbours(pages[index + 1]),
|
||||
};
|
||||
}
|
||||
|
||||
export { GetDocsFirstSlug, GetDocsHref, GetDocsNav, GetDocsPage, RenderDocsMarkdown };
|
||||
90
frontend/app/services/DocsMarkdown.js
Normal file
90
frontend/app/services/DocsMarkdown.js
Normal file
@@ -0,0 +1,90 @@
|
||||
/*
|
||||
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 };
|
||||
Reference in New Issue
Block a user