From ca562040a9aaf847ed7abe8e113e48bcf4e82018 Mon Sep 17 00:00:00 2001
From: John Coffey <john@coffeylabs.org>
Date: Mon, 12 Oct 2026 21:51:18 -0700
Subject: [PATCH] Manual: write the reference for the docs as they are now

docs.inbuxa.org moved from MkDocs to HotDog CMS: the reference lives in
docs-site/content/docs/reference, each page opens with front matter naming
its title (the docs' layout shows it, so a heading would show it twice), and
the index is the folder's own page, _index.md. The words, anchors and page
names are unchanged, so "Learn more" links land where they did.
---
 tools/build-manual.mjs | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/tools/build-manual.mjs b/tools/build-manual.mjs
index 1c05552..984a37e 100644
--- a/tools/build-manual.mjs
+++ b/tools/build-manual.mjs
@@ -7,7 +7,7 @@
 // tooltip or help panel makes (src/help/manual.ts) lands on its own entry.
 //
 //   node tools/build-manual.mjs --schema ../inbuxa-server/resources/schema/schema.json.gz \
-//                               --out ../inbuxa.org/docs-site/docs/reference
+//                               --out ../inbuxa.org/docs-site/content/docs/reference
 //
 // The words are the console's own: the help texts in src/help/texts.ts first,
 // the schema's descriptions where we haven't written any, and defaults
@@ -15,6 +15,10 @@
 // anchors come from manualPath(), the same function the console links with,
 // so the two can't drift apart. Run it again after a schema or help change;
 // it rewrites the whole directory.
+//
+// The docs site is HotDog CMS (MkDocs until October 2026): each page opens
+// with front matter naming its title, which the docs' layout shows, and the
+// index is the folder's own page, _index.md.
 
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -24,7 +28,7 @@ import { createServer } from 'vite';
 function arg(name) {
   const i = process.argv.indexOf(`--${name}`);
   if (i < 0 || !process.argv[i + 1]) {
-    console.error(`usage: build-manual.mjs --schema <schema.json.gz> --out <docs/reference>`);
+    console.error(`usage: build-manual.mjs --schema <schema.json.gz> --out <content/docs/reference>`);
     process.exit(2);
   }
   return process.argv[i + 1];
@@ -46,6 +50,11 @@ await vite.close();
 const WORDS = { on: 'On', off: 'Off', none: 'None' };
 
 /** Text for markdown: angle brackets would read as HTML. */
+/** A page's front matter: its title (JSON's quoting is YAML's). */
+function front(pageTitle) {
+  return ['---', `title: ${JSON.stringify(String(pageTitle))}`, '---', ''];
+}
+
 function md(text) {
   return String(text ?? '')
     .replace(/&/g, '&amp;')
@@ -212,8 +221,7 @@ function fieldEntry(scope, f) {
 }
 
 function schemaPage(name) {
-  const lines = [];
-  lines.push(`# ${md(title(name))}`, '');
+  const lines = front(title(name));
   const where = whereInConsole.get(name);
   if (where) lines.push(`*In the console: ${where.map(md).join(' › ')}*`, '');
   const text = about(name);
@@ -251,7 +259,7 @@ function schemaPage(name) {
 /** A page of the console's own, with what it's for (its options live in the code, not the schema). */
 function ownPage(name) {
   const help = PAGE_HELP[name];
-  const lines = [`# ${md(title(name))}`, ''];
+  const lines = front(title(name));
   const where = whereInConsole.get(name);
   if (where) lines.push(`*In the console: ${where.map(md).join(' › ')}*`, '');
   if (help?.about) lines.push(md(help.about), '');
@@ -284,8 +292,7 @@ for (const [name, render] of pages) {
 
 // The index: the console's menus first, then everything else
 const index = [
-  '# Reference',
-  '',
+  ...front('Reference'),
   'Every setting in the console, page by page: what it does, what it’s set to unless you change it, and the name the API uses. The **Learn more** link in a tooltip or a page’s help panel opens its entry here.',
   '',
   'These pages are generated from the server’s own description of its settings, with the console’s help text. To set things up step by step, start with [Run it](../run/topology.md) instead.',
@@ -321,6 +328,6 @@ if (rest.length) {
   for (const e of rest) index.push(`- [${md(title(e.name))}](${e.file})`);
   index.push('');
 }
-writeFileSync(join(outDir, 'index.md'), `${index.join('\n')}\n`);
+writeFileSync(join(outDir, '_index.md'), `${index.join('\n')}\n`);
 
 console.log(`wrote ${written.length} pages and an index to ${outDir}`);
-- 
2.54.0