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 };
|
||||
Reference in New Issue
Block a user