115 lines
4.1 KiB
JavaScript
115 lines
4.1 KiB
JavaScript
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 };
|