Files
dragonroll/frontend/app/services/Docs.js
Gitea OpenCode Agent 788f69efd3
All checks were successful
Test / test (push) Successful in 2s
Fix issue #79: Implement documentation
2026-10-15 19:07:09 +00:00

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 };