{{ $t(`docs.groups.${page.group}`) }}
+ + +{{ $t('docs.title') }}
+{{ $t('docs.not-found', { page: slug }) }}
+diff --git a/AGENTS.md b/AGENTS.md
index b2699f63..0de66540 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,11 +10,11 @@ Free/open-source helper for tabletop RPG campaigns (campaigns, markdown notes, f
items, maps, dice widgets, sounds).
- `backend/` — Node + **Express 5** + **Mongoose 9** (MongoDB) REST API, JWT auth, CommonJS, entry `src/index.js`.
-- `frontend/` — **Nuxt 4 / Vue 3** (`
- {{ $t(`docs.groups.${page.group}`) }} {{ $t('docs.not-found', { page: slug }) }} {{ $t('docs.title') }}
+
, , … 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 };
diff --git a/frontend/i18n/locales/ca/docs.json b/frontend/i18n/locales/ca/docs.json
new file mode 100644
index 00000000..37372dfc
--- /dev/null
+++ b/frontend/i18n/locales/ca/docs.json
@@ -0,0 +1,15 @@
+{
+ "title": "Documentació",
+ "contents": "Contingut",
+ "on-this-page": "En aquesta pàgina",
+ "open-app": "Obrir Dragonroll",
+ "previous": "Anterior",
+ "next": "Següent",
+ "not-found": "No hi ha cap pàgina de la documentació que es digui «{page}».",
+ "back-to-docs": "Tornar a la documentació",
+ "groups": {
+ "getting-started": "Primers passos",
+ "using-dragonroll": "Fer servir Dragonroll",
+ "integrations": "Integracions"
+ }
+}
diff --git a/frontend/i18n/locales/ca/main-menu.json b/frontend/i18n/locales/ca/main-menu.json
index 47355006..f8eac65b 100644
--- a/frontend/i18n/locales/ca/main-menu.json
+++ b/frontend/i18n/locales/ca/main-menu.json
@@ -2,6 +2,7 @@
"main-menu": "Menú principal",
"edit-profile": "Editar perfil",
"create-campaign": "Crear campanya",
+ "documentation": "Documentació",
"log-out": "Tanca la sessió",
"settings": "Configuració",
"exit": "Sortir"
diff --git a/frontend/i18n/locales/en/docs.json b/frontend/i18n/locales/en/docs.json
new file mode 100644
index 00000000..f3663a55
--- /dev/null
+++ b/frontend/i18n/locales/en/docs.json
@@ -0,0 +1,15 @@
+{
+ "title": "Documentation",
+ "contents": "Contents",
+ "on-this-page": "On this page",
+ "open-app": "Open Dragonroll",
+ "previous": "Previous",
+ "next": "Next",
+ "not-found": "There is no documentation page called “{page}”.",
+ "back-to-docs": "Back to the documentation",
+ "groups": {
+ "getting-started": "Getting started",
+ "using-dragonroll": "Using Dragonroll",
+ "integrations": "Integrations"
+ }
+}
diff --git a/frontend/i18n/locales/en/main-menu.json b/frontend/i18n/locales/en/main-menu.json
index b1f8c866..63798bdd 100644
--- a/frontend/i18n/locales/en/main-menu.json
+++ b/frontend/i18n/locales/en/main-menu.json
@@ -2,6 +2,7 @@
"main-menu": "Main menu",
"edit-profile": "Edit profile",
"create-campaign": "Create Campaign",
+ "documentation": "Documentation",
"log-out": "Log out",
"settings": "Settings",
"exit": "Exit"
diff --git a/frontend/i18n/locales/es/docs.json b/frontend/i18n/locales/es/docs.json
new file mode 100644
index 00000000..87bf3f23
--- /dev/null
+++ b/frontend/i18n/locales/es/docs.json
@@ -0,0 +1,15 @@
+{
+ "title": "Documentación",
+ "contents": "Contenido",
+ "on-this-page": "En esta página",
+ "open-app": "Abrir Dragonroll",
+ "previous": "Anterior",
+ "next": "Siguiente",
+ "not-found": "No hay ninguna página de la documentación que se llame «{page}».",
+ "back-to-docs": "Volver a la documentación",
+ "groups": {
+ "getting-started": "Primeros pasos",
+ "using-dragonroll": "Usar Dragonroll",
+ "integrations": "Integraciones"
+ }
+}
diff --git a/frontend/i18n/locales/es/main-menu.json b/frontend/i18n/locales/es/main-menu.json
index 3881bc27..80716fe5 100644
--- a/frontend/i18n/locales/es/main-menu.json
+++ b/frontend/i18n/locales/es/main-menu.json
@@ -2,6 +2,7 @@
"main-menu": "Menú principal",
"edit-profile": "Editar perfil",
"create-campaign": "Crear campanya",
+ "documentation": "Documentación",
"log-out": "Cerrar sesión",
"settings": "Configuración",
"exit": "Salir"
diff --git a/tests/docs.test.js b/tests/docs.test.js
new file mode 100644
index 00000000..409792df
--- /dev/null
+++ b/tests/docs.test.js
@@ -0,0 +1,328 @@
+// Tests for the documentation under /docs (Syndria98/dragonroll#79): the markdown pages are the
+// documentation, so what has to stay right is (1) the pages are well formed — a title, a slug, a
+// numbered group, translations for the group's label, and no link pointing at a page that does not
+// exist, (2) the page about an integration really documents what that integration offers, which is
+// checked against the sources that define it: the slash commands of discord-bot/src/commands.js and
+// the commands the Obsidian plugin registers, and (3) the routes: /docs and /docs/ render the
+// documentation and every other address still opens the window app.
+//
+// `frontend/app/services/DocsMarkdown.js` is the pure part of the docs (headings, slugs, titles) and
+// is loaded straight from source, the way the other tests load the frontend services; it imports
+// nothing, so the repository root's no-dependencies rule holds. `Docs.js` itself is not loaded: it
+// reads the markdown through `import.meta.glob`, which only Vite can answer.
+//
+// Run with `npm test` from the repository root, or `node --test tests/`.
+
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const vm = require("node:vm");
+
+function readRepoFile(...parts) {
+ return fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
+}
+
+function loadDocsMarkdown() {
+ const source = readRepoFile("frontend", "app", "services", "DocsMarkdown.js");
+ return vm.compileFunction(source.replace("export {", "return {") , [], {
+ parsingContext: vm.createContext({}),
+ })();
+}
+
+const docs = loadDocsMarkdown();
+
+// The documentation pages, as the folder layout defines them.
+const docsRoot = path.join(__dirname, "..", "frontend", "app", "content", "docs");
+const docPages = fs.readdirSync(docsRoot, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory())
+ .sort((left, right) => left.name.localeCompare(right.name))
+ .flatMap((group) => fs.readdirSync(path.join(docsRoot, group.name))
+ .filter((file) => file.endsWith(".md"))
+ .sort()
+ .map((file) => ({
+ group: group.name.replace(/^\d+-/, ""),
+ slug: file.replace(/^\d+-/, "").replace(/\.md$/, ""),
+ markdown: fs.readFileSync(path.join(docsRoot, group.name, file), "utf8"),
+ }))
+ );
+
+const slugs = new Set(docPages.map((page) => page.slug));
+const groups = [...new Set(docPages.map((page) => page.group))];
+
+const pageAbout = (slug) => docPages.find((page) => page.slug === slug);
+
+// --- The heading helpers the sidebar and the anchors are built from ---
+
+test("a heading's slug comes out of its words, whatever form they arrive in", () => {
+ assert.equal(docs.Slugify("Link a world"), "link-a-world");
+ assert.equal(docs.Slugify(" Auto-sync, and one actor "), "auto-sync-and-one-actor");
+ assert.equal(docs.Slugify("Dragonroll: Force Sync!"), "dragonroll-force-sync");
+});
+
+test("the anchor built from a heading's markdown is the one built from its HTML", () => {
+ // The sidebar slugs the markdown source and the renderer slugs what marked produced, so the two
+ // have to land on the same anchor for a sidebar link to land on its section.
+ const pairs = [
+ ["**Link** a `world`", "Link a world"],
+ ["Commands & characters", "Commands & characters"],
+ ["[Foundry](/docs/foundry) worlds", 'Foundry worlds'],
+ ["It's here", "It's here"],
+ ];
+
+ for (const [markdown, html] of pairs) {
+ assert.equal(docs.Slugify(markdown), docs.Slugify(html), `slug of ${markdown}`);
+ }
+});
+
+test("repeated headings get distinct anchors, in the order they are written", () => {
+ const slug = docs.CreateHeadingSlugger();
+ assert.equal(slug("Setup"), "setup");
+ assert.equal(slug("setup"), "setup-1");
+ assert.equal(slug("Setup"), "setup-2");
+});
+
+test("the headings of a page are listed in order, with their anchors", () => {
+ const headings = docs.HeadingsFromMarkdown([
+ "# Connecting a service",
+ "",
+ "## How a connection works",
+ "text",
+ "### What it allows",
+ "```sh",
+ "# not a heading",
+ "```",
+ "## Next",
+ ].join("\n"));
+
+ // The service is loaded from another realm, so the values are copied out before being compared.
+ assert.deepEqual(
+ JSON.parse(JSON.stringify(headings.map(({ depth, text, slug }) => ({ depth, text, slug })))),
+ [
+ { depth: 1, text: "Connecting a service", slug: "connecting-a-service" },
+ { depth: 2, text: "How a connection works", slug: "how-a-connection-works" },
+ { depth: 3, text: "What it allows", slug: "what-it-allows" },
+ { depth: 2, text: "Next", slug: "next" },
+ ]
+ );
+});
+
+test("a page takes its title from its first heading", () => {
+ assert.equal(docs.TitleFromMarkdown("# Your first campaign\n\n## Signing in"), "Your first campaign");
+ assert.equal(docs.TitleFromMarkdown("no heading here"), "");
+});
+
+// --- The pages themselves ---
+
+test("the documentation has pages, in numbered groups", () => {
+ assert.ok(docPages.length >= 5, `expected several documentation pages, found ${docPages.length}`);
+
+ for (const page of docPages) {
+ const folder = `${page.group}`;
+ assert.ok(folder.length > 0, `${page.slug} sits in an oddly named folder`);
+ assert.match(page.slug, /^[a-z0-9]+(-[a-z0-9]+)*$/, `${page.slug} is not a url-friendly slug`);
+ }
+});
+
+test("every page has a title, and no two pages share a slug", () => {
+ const seen = new Set();
+
+ for (const page of docPages) {
+ const title = docs.TitleFromMarkdown(page.markdown);
+ assert.ok(title, `${page.slug} has no heading to title it`);
+ assert.ok(!seen.has(page.slug), `${page.slug} is published twice`);
+ seen.add(page.slug);
+ }
+ assert.equal(seen.size, docPages.length);
+});
+
+test("every page has sections, which is what the sidebar lists beside it", () => {
+ for (const page of docPages) {
+ const sections = docs.HeadingsFromMarkdown(page.markdown).filter((heading) => heading.depth > 1);
+ assert.ok(sections.length, `${page.slug} has no section headings to list`);
+ }
+});
+
+test("every group has a sidebar label in every locale", () => {
+ const labels = ["en", "es", "ca"].map((locale) =>
+ JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "docs.json"))
+ );
+
+ assert.ok(labels.every((label) => label.groups), "each docs.json namespace needs a `groups` object");
+
+ for (const group of groups) {
+ for (const label of labels) {
+ const text = label.groups[group];
+ assert.ok(text, `the "${group}" group has no label in its docs.json`);
+ assert.notEqual(text, group, `the "${group}" label is untranslated`);
+ }
+ }
+});
+
+test("the pages only link to pages that are published", () => {
+ for (const page of docPages) {
+ for (const link of page.markdown.matchAll(/\]\((\/docs\/?[a-z0-9-]*)\)/g)) {
+ const target = link[1].replace("/docs/", "");
+ if (!target) continue; // /docs itself
+ assert.ok(slugs.has(target), `${page.slug} links to ${link[1]}, which is not published`);
+ }
+ }
+});
+
+test("the three integrations each have their own page", () => {
+ for (const slug of ["discord", "foundry", "obsidian"]) {
+ assert.ok(pageAbout(slug), `${slug} has no documentation page`);
+ }
+ assert.ok(pageAbout("connecting-a-service"), "the shared way of connecting a service is undocumented");
+});
+
+// --- The integrations pages describe what the integrations actually offer ---
+
+// discord-bot/src/commands.js builds the slash commands with discord.js, which the repository root
+// does not install: the builder is stubbed by one that records the names it is given.
+function loadSlashCommands() {
+ const registered = [];
+
+ class Builder {
+ constructor() {
+ this.name = "";
+ this.parent = null;
+ this.children = [];
+ this.optionNames = [];
+ }
+
+ setName(name) { this.name = name; return this; }
+ setDescription() { return this; }
+ setContexts() { return this; }
+ setRequired() { return this; }
+ setMaxLength() { return this; }
+ setAutocomplete() { return this; }
+ addChoices() { return this; }
+ addStringOption(configure) { configure(new Builder()); return this; }
+ addBooleanOption(configure) { configure(new Builder()); return this; }
+ addSubcommand(configure) {
+ const sub = new Builder();
+ sub.parent = this;
+ configure(sub);
+ this.children.push(sub);
+ return this;
+ }
+ }
+
+ class SlashCommandBuilder extends Builder {
+ constructor() {
+ super();
+ registered.push(this);
+ }
+ }
+
+ const moduleStub = { exports: {} };
+ vm.compileFunction(readRepoFile("discord-bot", "src", "commands.js"), ["require", "module", "exports"])(
+ (id) => {
+ if (id === "discord.js") return { InteractionContextType: { Guild: 0 }, SlashCommandBuilder };
+ throw new Error(`require("${id}") is not stubbed`);
+ },
+ moduleStub,
+ moduleStub.exports
+ );
+
+ const names = [];
+ for (const command of registered) {
+ names.push(command.name);
+ for (const sub of command.children) names.push(`${command.name} ${sub.name}`);
+ }
+ return names;
+}
+
+test("the Discord page lists every command the bot declares", () => {
+ const about = pageAbout("discord");
+ const commands = loadSlashCommands();
+
+ // Sanity check on the stub before it is trusted to list anything.
+ assert.ok(commands.includes("characters"), `expected the bot's commands, got ${commands.join(", ")}`);
+ assert.ok(commands.includes("dragonroll connect"));
+
+ for (const command of commands) {
+ assert.ok(
+ about.markdown.includes("`/" + command),
+ `the Discord page does not document /${command}`
+ );
+ }
+});
+
+// The Obsidian plugin registers each command palette entry with `this.addCommand({ id, name, … })`.
+function loadObsidianCommands() {
+ const source = readRepoFile("obsidian-plugin", "main.js");
+ const commands = [...source.matchAll(
+ /this\.addCommand\(\{\s*id:\s*["']([^"']+)["'],\s*name:\s*["']([^"']+)["']/g
+ )].map((match) => ({ id: match[1], name: match[2] }));
+
+ // Sanity check on the extraction before it is trusted to list anything.
+ assert.ok(commands.length >= 2, `expected the plugin's commands, got ${commands.length}`);
+
+ return commands;
+}
+
+test("the Obsidian page lists the commands the plugin registers", () => {
+ const about = pageAbout("obsidian");
+
+ for (const command of loadObsidianCommands()) {
+ assert.ok(
+ about.markdown.includes(`**${command.name}**`),
+ `the Obsidian page does not document "${command.name}" (${command.id})`
+ );
+ }
+});
+
+test("the Foundry page covers what the world and the campaign do with each other", () => {
+ const about = pageAbout("foundry").markdown;
+
+ for (const topic of ["Auto-sync", "Force Sync", "item directory", "Pairing Status"]) {
+ assert.ok(about.includes(topic), `the Foundry page never mentions ${topic}`);
+ }
+});
+
+// --- The routes ---
+
+test("the app renders whichever page the address asks for", () => {
+ const root = readRepoFile("frontend", "app", "app.vue");
+ assert.match(root, //, "app.vue has to render the matched page");
+ assert.doesNotMatch(root, /CreateWindow/, "the window app boots from AppShell, not from app.vue");
+});
+
+test("the documentation has a route of its own, and the app keeps the rest", () => {
+ const pages = path.join("frontend", "app", "pages");
+ const docsRoutes = ["docs/index.vue", "docs/[slug].vue"];
+
+ for (const route of docsRoutes) {
+ assert.match(
+ readRepoFile(pages, route),
+ //,
+ `${route} has to render the documentation`
+ );
+ }
+
+ for (const route of ["index.vue", "[...all].vue"]) {
+ assert.match(
+ readRepoFile(pages, route),
+ //,
+ `${route} has to open the window app`
+ );
+ }
+
+ // The catch-all is what keeps /link/authorize, and every path a service already links to, alive.
+ const shell = readRepoFile("frontend", "app", "components", "views", "AppShell.vue");
+ assert.ok(shell.includes("/link/authorize"), "the service link screen has to stay reachable");
+ assert.ok(shell.includes("/discord/authorize"), "the legacy Discord link has to stay reachable");
+});
+
+test("the main menu points at the documentation", () => {
+ const menu = readRepoFile("frontend", "app", "components", "windows", "MainMenuWindow.vue");
+ assert.match(menu, /href="\/docs"/, "the main menu has to link to /docs");
+ assert.match(menu, /main-menu\.documentation/);
+
+ for (const locale of ["en", "es", "ca"]) {
+ const strings = JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "main-menu.json"));
+ assert.ok(strings.documentation, `${locale} has no label for the documentation link`);
+ }
+});