hdoc-tools 0.60.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.60.0",
+	"version": "0.61.0",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {
@@ -12,7 +12,6 @@
 		"hdoc-build.js",
 		"hdoc-build-db.js",
 		"hdoc-build-embeddings.js",
-		"hdoc-build-onyx.js",
 		"hdoc-build-pdf.js",
 		"hdoc-bump.js",
 		"hdoc-content-routes.js",
@@ -29,6 +28,7 @@
 		"hdoc-toc.js",
 		"hdoc-validate.js",
 		"hdoc-validate-config.js",
+		"hdoc-validate-interbook.js",
 		"hdoc-ver.js",
 		"validateNodeVer.js",
 		".puppeteerrc.cjs",

package/schemas/hdocbook-project.schema.json

@@ -67,6 +67,26 @@
         "external_link_warnings": {
           "type": "boolean",
           "description": "When true, external link failures are reported as warnings rather than errors."
+        },
+        "spellcheckDictionary": {
+          "type": "array",
+          "description": "Words to exclude from the British English spellcheck across all documents in the book.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "ai": {
+      "type": "object",
+      "description": "Configuration for the hdoc edit AI assist feature.",
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "Anthropic model ID used by the hdoc edit AI assist feature."
+        },
+        "maxTokens": {
+          "type": "integer",
+          "description": "Maximum response tokens for AI assist requests."
         }
       }
     },

package/schemas/hdocbook.schema.json

@@ -4,7 +4,7 @@
   "title": "HDocBook Configuration",
   "description": "Schema for hdocbook.json - book metadata, navigation, and publishing configuration",
   "type": "object",
-  "required": ["docId", "title", "description", "version", "productFamily", "audience", "navigation"],
+  "required": ["docId", "title", "version", "productFamily", "audience", "navigation"],
   "additionalProperties": false,
   "properties": {
     "docId": {
@@ -98,7 +98,7 @@
       "properties": {
         "items": {
           "type": "array",
-          "description": "Top-level navigation items. Maximum three levels of nesting are supported.",
+          "description": "Top-level navigation items. Maximum five levels of nesting are supported.",
           "minItems": 1,
           "items": { "$ref": "#/$defs/navigationItem" }
         }
@@ -128,6 +128,10 @@
           "type": "string",
           "description": "Display text for the navigation item."
         },
+        "id": {
+          "type": "string",
+          "description": "Opaque node identifier written by the hdoc edit navigation editor. Optional."
+        },
         "link": {
           "type": "string",
           "description": "Path to the content page. Ignored when 'items' is present."

package/ui/js/doc.hornbill.js

@@ -7,36 +7,14 @@ let jqDocumentHeader = null;
 let jqLeftNav = null;
 const global = { stateParams: {}, lastLayoutClass: "" };
 
-//-- Mermaid client-side rendering config — mirrors templates/mermaid-theme.yaml.
-//-- (PDFs are still rendered to SVG server-side by hdoc build; this is HTML-only.)
-const HB_MERMAID_CONFIG = {
-	startOnLoad: false,
-	theme: "base",
-	themeVariables: {
-		background: "transparent",
-		fontSize: "14px",
-		primaryColor: "#85D2FF",
-		primaryColorLight: "#85D2FF",
-		primaryColorDark: "#0065CB",
-		secondaryColor: "#219BFF",
-		secondaryColorLight: "#85D2FF",
-		secondaryColorDark: "#0C4C8C",
-		tertiaryColor: "#219BFF",
-		tertiaryColorLight: "#85D2FF",
-		tertiaryColorDark: "#0C4C8C",
-		lineColor: "#808080",
-		border1: "#606060",
-		textColor: "#A0A0A0",
-		titleColor: "#A0A0A0",
-		labelColor: "#404040",
-		loopTextColor: "#A0A0A0",
-		nodeTextColor: "#404040",
-		labelTextColor: "#404040",
-		pieSectionTextColor: "#404040",
-		nodeBorder: "#219BFF",
-		nodeBg: "transparent",
-	},
-};
+//-- Mermaid theme lives in js/mermaid-theme.json — the SINGLE source shared
+//-- with the server-side PDF SVG bake (hdoc build reads the same file). Fetch
+//-- failure falls back to the plain base theme rather than blocking rendering.
+function hbFetchMermaidTheme() {
+	return fetch("js/mermaid-theme.json") //-- resolves against <base href>
+		.then((r) => (r.ok ? r.json() : null))
+		.catch(() => null);
+}
 
 //-- Lazy-load the Mermaid bundle (~3MB) only when a page actually contains a
 //-- diagram. Resolves to window.mermaid, initialised once.
@@ -44,20 +22,29 @@ let hbMermaidLoadPromise = null;
 function hbLoadMermaid() {
 	if (window.mermaid) return Promise.resolve(window.mermaid);
 	if (hbMermaidLoadPromise) return hbMermaidLoadPromise;
-	hbMermaidLoadPromise = new Promise((resolve, reject) => {
-		const el = document.createElement("script");
-		el.src = "js/mermaid.min.js"; //-- resolves against <base href> (site root)
-		el.onload = () => {
-			try {
-				window.mermaid.initialize(HB_MERMAID_CONFIG);
-				resolve(window.mermaid);
-			} catch (e) {
-				reject(e);
-			}
-		};
-		el.onerror = () => reject(new Error("failed to load js/mermaid.min.js"));
-		document.head.appendChild(el);
-	});
+	hbMermaidLoadPromise = hbFetchMermaidTheme().then(
+		(theme) =>
+			new Promise((resolve, reject) => {
+				const el = document.createElement("script");
+				el.src = "js/mermaid.min.js"; //-- resolves against <base href> (site root)
+				el.onload = () => {
+					try {
+						window.mermaid.initialize(
+							Object.assign(
+								{ startOnLoad: false },
+								theme || { theme: "base" },
+							),
+						);
+						resolve(window.mermaid);
+					} catch (e) {
+						reject(e);
+					}
+				};
+				el.onerror = () =>
+					reject(new Error("failed to load js/mermaid.min.js"));
+				document.head.appendChild(el);
+			}),
+	);
 	return hbMermaidLoadPromise;
 }
 

package/ui/js/mermaid-theme.json

@@ -0,0 +1,27 @@
+{
+	"theme": "base",
+	"themeVariables": {
+		"background": "transparent",
+		"fontSize": "14px",
+		"primaryColor": "#85D2FF",
+		"primaryColorLight": "#85D2FF",
+		"primaryColorDark": "#0065CB",
+		"secondaryColor": "#219BFF",
+		"secondaryColorLight": "#85D2FF",
+		"secondaryColorDark": "#0C4C8C",
+		"tertiaryColor": "#219BFF",
+		"tertiaryColorLight": "#85D2FF",
+		"tertiaryColorDark": "#0C4C8C",
+		"lineColor": "#808080",
+		"border1": "#606060",
+		"textColor": "#A0A0A0",
+		"titleColor": "#A0A0A0",
+		"labelColor": "#404040",
+		"loopTextColor": "#A0A0A0",
+		"nodeTextColor": "#404040",
+		"labelTextColor": "#404040",
+		"pieSectionTextColor": "#404040",
+		"nodeBorder": "#219BFF",
+		"nodeBg": "transparent"
+	}
+}

package/hdoc-build-onyx.js

@@ -1,134 +0,0 @@
-(() => {
-	const fs = require("node:fs");
-	const path = require("node:path");
-
-	// Replicates the URL normalisation logic from populate_index so page keys match.
-	function to_page_path(file) {
-		let p = file.relative_path.replaceAll("\\", "/");
-		if (
-			p.endsWith("/index.md") ||
-			p.endsWith("/index.html") ||
-			p.endsWith("/index.htm")
-		) {
-			p = p.substring(0, p.lastIndexOf("/"));
-		}
-		return `/${p.replace(path.extname(file.relative_path), "")}`;
-	}
-
-	// Groups index_records into one entry per page, preserving section order.
-	function build_pages(index_records) {
-		const pages = new Map();
-		for (const file of index_records) {
-			if (file.inline) continue;
-			const page_path = to_page_path(file);
-			if (!pages.has(page_path)) {
-				pages.set(page_path, {
-					page_path,
-					title: file.index_html.fm_props.title || "",
-					keywords: file.keywords || "",
-					status: file.status || "release",
-					lastmod: file.lastmod || null,
-					sections: [],
-				});
-			}
-			const text = (file.index_html.text || "").trim();
-			if (text) pages.get(page_path).sections.push(text);
-		}
-		return Array.from(pages.values());
-	}
-
-	// Returns an ISO 8601 string, or null if the value is absent or unparseable.
-	function safe_iso(value) {
-		if (!value) return null;
-		const d = new Date(value);
-		return Number.isNaN(d.getTime()) ? null : d.toISOString();
-	}
-
-	exports.populate_onyx_index = (
-		work_path_content,
-		doc_id,
-		book_config,
-		index_records,
-		base_url = "",
-		verbose = false,
-	) => {
-		const response = {
-			success: false,
-			document_count: 0,
-			error: "",
-		};
-
-		const pages = build_pages(index_records);
-		const canonical_base = base_url.replace(/\/$/, "");
-		const metadata_entries = [];
-
-		for (const page of pages) {
-			// e.g.  onyx/getting-started/index.txt  or  onyx/reference/api.txt
-			const txt_rel = `_onyx${page.page_path}.txt`;
-			const txt_abs = path.join(work_path_content, txt_rel);
-
-			fs.mkdirSync(path.dirname(txt_abs), { recursive: true });
-
-			// Plain-text body: title, keywords hint, then each section separated by
-			// a blank line so Onyx's chunker sees natural paragraph boundaries.
-			const lines = [];
-			if (page.title) lines.push(page.title, "");
-			if (page.keywords) lines.push(`Keywords: ${page.keywords}`, "");
-			for (const section of page.sections) {
-				lines.push(section, "");
-			}
-
-			try {
-				fs.writeFileSync(txt_abs, lines.join("\n").trimEnd(), "utf8");
-			} catch (e) {
-				response.error = `Failed to write ${txt_rel}: ${e.message}`;
-				return response;
-			}
-
-			if (verbose) console.log(`Onyx: wrote ${txt_rel}`);
-
-			const entry = {
-				filename: txt_rel.replaceAll("\\", "/"),
-				link: canonical_base
-					? `${canonical_base}${page.page_path}`
-					: page.page_path,
-				primary_owners: [],
-				secondary_owners: [],
-				metadata: {
-					book_id: doc_id,
-					product_family: book_config.productFamily || "",
-					audience: Array.isArray(book_config.audience)
-						? book_config.audience.join(",")
-						: "",
-					tags: Array.isArray(book_config.tags)
-						? book_config.tags.join(",")
-						: "",
-					status: page.status,
-				},
-			};
-			const updated_at = safe_iso(page.lastmod);
-			if (updated_at) entry.doc_updated_at = updated_at;
-			metadata_entries.push(entry);
-
-			response.document_count++;
-		}
-
-		const meta_path = path.join(work_path_content, ".onyx_metadata.json");
-		try {
-			fs.writeFileSync(
-				meta_path,
-				JSON.stringify(metadata_entries, null, 2),
-				"utf8",
-			);
-		} catch (e) {
-			response.error = `Failed to write .onyx_metadata.json: ${e.message}`;
-			return response;
-		}
-
-		response.success = true;
-		console.log(
-			`\nOnyx Index Build Complete: ${response.document_count} document records created.`,
-		);
-		return response;
-	};
-})();

package/templates/mermaid-theme.yaml

@@ -1,28 +0,0 @@
-config:
-  theme: 'base'
-  themeVariables:
-    background: transparent
-    fontSize: 14px
-    primaryColor: "#85D2FF"            # Medium blue
-    primaryColorLight: "#85D2FF"       # Light accent blue
-    primaryColorDark: "#0065CB"        # Medium-dark blue
-
-    secondaryColor: "#219BFF"          # Medium blue
-    secondaryColorLight: "#85D2FF"       # Light accent blue
-    secondaryColorDark: "#0C4C8C"        # Medium-dark blue
-
-    tertiaryColor: "#219BFF"          # Medium blue
-    tertiaryColorLight: "#85D2FF"       # Light accent blue
-    tertiaryColorDark: "#0C4C8C"        # Medium-dark blue
-
-    lineColor: "#808080"               # Medium grey for lines
-    border1: "#606060"                 # Darker grey for borders
-    textColor: "#A0A0A0"               # Light grey text (visible on both)
-    titleColor: "#A0A0A0"
-    labelColor: "#404040"
-    loopTextColor: "#A0A0A0"
-    nodeTextColor: "#404040"
-    labelTextColor: "#404040"
-    pieSectionTextColor: "#404040"
-    nodeBorder: "#219BFF"              # Match node border to primary blue
-    nodeBg: transparent