hdoc-tools 0.47.4 → 0.48.0

package/hdoc-build-onyx.js

@@ -0,0 +1,134 @@
+(() => {
+	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/hdoc-build.js

@@ -7,6 +7,7 @@
 	const hdoc_validate = require(path.join(__dirname, "hdoc-validate.js"));
 	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
 	const hdoc_build_db = require(path.join(__dirname, "hdoc-build-db.js"));
+	const hdoc_build_onyx = require(path.join(__dirname, "hdoc-build-onyx.js"));
 	const hdoc_build_pdf = require(path.join(__dirname, "hdoc-build-pdf.js"));
 	const hdoc_index = require(path.join(__dirname, "hdoc-db.js"));
 	const archiver = require("archiver");

package/hdoc-validate.js

@@ -529,7 +529,10 @@ const { error } = require("node:console");
 			const valid_url = hdoc.valid_url(links[i]);
 			if (!valid_url) {
 				// Could be a relative path, check
-				if (links[i].startsWith("/") && !links[i].startsWith("/#")) {
+				if (links[i].startsWith("#") || links[i].startsWith("/#")) {
+					//Flat Anchor - validate we have a same-file hit
+					isHashAnchor(htmlFile, links[i]);
+				} else if (links[i].startsWith("/") && !links[i].startsWith("/#")) {
 					let link_segments = links[i].split("/");
 					if (link_segments[0] === "") link_segments.shift();
 					const link_root = link_segments[0] === "_books" ? link_segments[1] : link_segments[0];
@@ -542,14 +545,11 @@ const { error } = require("node:console");
 					}
 
 					// Checking for internal links in other books - can't easily validate those here, returning
-					if (link_segments.length > 1 && link_root !== hdocbook_config.docId) {
+					if ((link_segments.length > 1 && link_root !== hdocbook_config.docId) || (link_segments.length === 1 && link_root !== hdocbook_config.docId && link_root !== "index")) {
 						fs.appendFileSync(skip_link_file, `${links[i]}\n`);
 						continue;
 					}
 					isRelativePath(source_path, htmlFile, links[i]);
-				} else if (links[i].startsWith("#") || links[i].startsWith("/#")) {
-					//Flat Anchor - validate we have a same-file hit
-					isHashAnchor(htmlFile, links[i]);
 				} else {
 					const error_message = processErrorMessage(`Root relative links should start with a forward-slash: ${links[i]}`, markdown_paths.relativePath, markdown_content, links[i]);
 					errors[htmlFile.relativePath].push(error_message);

package/hdoc.js

@@ -105,6 +105,7 @@
 	let gen_exclude = false;
 	let bump_type = "patch"; // To generate spellcheck exclusions for all files
 	let output_links = true;
+	let onyx_index = false;
 
 	// Get options from command args
 	for (let x = 0; x < process.argv.length; x++) {
@@ -151,6 +152,8 @@
 			console_color = false;
 		} else if (process.argv[x].toLowerCase() === "--no-links") {
 			output_links = false;
+		} else if (process.argv[x].toLowerCase() === "--onyx") {
+			onyx_index = true;
 		}
 	}
 	source_path = hdoc.true_case_path_sync(source_path);
@@ -186,6 +189,7 @@
 			gen_exclude,
 			build_version,
 			output_links,
+			onyx_index,
 		);
 	} else if (command.toLowerCase() === "createdocs") {
 		const creator = require(path.join(__dirname, "hdoc-create.js"));
@@ -200,6 +204,7 @@
 			gen_exclude,
 			build_version,
 			output_links,
+			onyx_index,
 		);
 	} else if (command.toLowerCase() === "stats") {
 		const stats = require(path.join(__dirname, "hdoc-stats.js"));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.47.4",
+	"version": "0.48.0",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {
@@ -11,6 +11,7 @@
 		"hdoc-db.js",
 		"hdoc-build.js",
 		"hdoc-build-db.js",
+		"hdoc-build-onyx.js",
 		"hdoc-build-pdf.js",
 		"hdoc-bump.js",
 		"hdoc-create.js",