hdoc-tools 0.47.5 → 0.50.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

@@ -5,8 +5,10 @@
 	const path = require("node:path");
 	const puppeteer = require("puppeteer");
 	const hdoc_validate = require(path.join(__dirname, "hdoc-validate.js"));
+	const hdoc_validate_config = require(path.join(__dirname, "hdoc-validate-config.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");
@@ -976,6 +978,17 @@
 			);
 			process.exit(1);
 		}
+
+		const project_config_errors = hdoc_validate_config.validate_project(hdocbook_project);
+		if (project_config_errors.length > 0) {
+			console.log("\r\n-----------------------");
+			console.log("   Validation Output   ");
+			console.log("-----------------------");
+			for (const err of project_config_errors) console.error(`- ${err}`);
+			console.error(`\r\n${project_config_errors.length} Configuration Error${project_config_errors.length !== 1 ? 's' : ''} Found in hdocbook-project.json`);
+			process.exit(1);
+		}
+
 		doc_id = hdocbook_project.docId;
 
 		if (
@@ -1006,7 +1019,12 @@
 		const work_path = path.join(source_path, "_work");
 		const work_hdocbook_path = path.join(work_path, doc_id, "hdocbook.json");
 
-		hdocbook_config = require(hdocbook_path);
+		try {
+			hdocbook_config = require(hdocbook_path);
+		} catch (e) {
+			console.error(`File not found: ${doc_id}/hdocbook.json\n`);
+			process.exit(1);
+		}
 		if (build_version !== "") {
 			if (build_version.match(regex_version)) {
 				hdocbook_config.version = build_version;
@@ -1017,6 +1035,16 @@
 			}
 		}
 
+		const book_config_errors = hdoc_validate_config.validate_book(hdocbook_config, doc_id);
+		if (book_config_errors.length > 0) {
+			console.log("\r\n-----------------------");
+			console.log("   Validation Output   ");
+			console.log("-----------------------");
+			for (const err of book_config_errors) console.error(`- ${err}`);
+			console.error(`\r\n${book_config_errors.length} Configuration Error${book_config_errors.length !== 1 ? 's' : ''} Found in ${doc_id}/hdocbook.json`);
+			process.exit(1);
+		}
+
 		if (!hdocbook_config.version.match(regex_version)) {
 			console.error(
 				`ERROR: Version number does not match required format - ${hdocbook_config.version}\n`,

package/hdoc-help.js

@@ -35,6 +35,7 @@ Commands
      - Use the '--set-version 1.2.3' argument to set the version number of the built book. 
      - Use the '--no-color' argument to remove any color control characters from the output.
      - Use the '--no-links' argument to skip link output to CLI during validation.
+     - Use the '--quiet' argument to suppress most console output, and only output validation errors if they are found.
 
  - bump
     Updates the semantic version number of the current book. If no options are specified, then the default of patch is applied:

package/hdoc-validate-config.js

@@ -0,0 +1,321 @@
+(() => {
+	const path = require("node:path");
+	const regex_doc_id = /^[a-z][a-z0-9-]+$/;
+	const regex_version = /^[0-9]{1,3}[.][0-9]{1,3}[.][0-9]{1,6}$/;
+
+	const hdocbook_schema = require(path.join(__dirname, "schemas", "hdocbook.schema.json"));
+	const valid_audience = hdocbook_schema.properties.audience.items.enum;
+	const valid_product_families = hdocbook_schema.properties.productFamily.enum;
+
+	const project_schema = require(path.join(__dirname, "schemas", "hdocbook-project.schema.json"));
+	const project_top_keys = Object.keys(project_schema.properties);
+	const project_pdf_keys = Object.keys(project_schema.properties.pdfGeneration.properties);
+	const project_validation_keys = Object.keys(project_schema.properties.validation.properties);
+	const project_redirect_keys = Object.keys(project_schema.properties.redirects.items.properties);
+	const redirect_valid_codes = project_schema.properties.redirects.items.properties.code.enum;
+
+	// Reports any keys in obj that are not in the allowed set.
+	const check_extra_keys = (obj, allowed, path, file, errors) => {
+		for (const key of Object.keys(obj)) {
+			if (!allowed.includes(key)) {
+				errors.push(`${file}: "${path ? path + '.' : ''}${key}" is not a recognised property`);
+			}
+		}
+	};
+
+	const validate_nav_item = (item, path, errors, depth) => {
+		if (typeof item !== 'object' || Array.isArray(item) || item === null) {
+			errors.push(`hdocbook.json: "${path}" must be an object`);
+			return;
+		}
+		check_extra_keys(item, ['text', 'link', 'expand', 'draft', 'items'], path, 'hdocbook.json', errors);
+		if (!item.text || typeof item.text !== 'string') {
+			errors.push(`hdocbook.json: "${path}.text" is required and must be a non-empty string`);
+		}
+		if (item.link !== undefined && typeof item.link !== 'string') {
+			errors.push(`hdocbook.json: "${path}.link" must be a string`);
+		}
+		if (item.expand !== undefined && typeof item.expand !== 'boolean') {
+			errors.push(`hdocbook.json: "${path}.expand" must be a boolean`);
+		}
+		if (item.draft !== undefined && typeof item.draft !== 'boolean') {
+			errors.push(`hdocbook.json: "${path}.draft" must be a boolean`);
+		}
+		if (item.items !== undefined) {
+			if (!Array.isArray(item.items)) {
+				errors.push(`hdocbook.json: "${path}.items" must be an array`);
+			} else if (depth >= 3) {
+				errors.push(`hdocbook.json: "${path}.items" exceeds the maximum navigation nesting depth of 3 levels`);
+			} else {
+				for (let i = 0; i < item.items.length; i++) {
+					validate_nav_item(item.items[i], `${path}.items[${i}]`, errors, depth + 1);
+				}
+			}
+		}
+	};
+
+	// Validates the structure of hdocbook-project.json
+	const validate_project = (config) => {
+		const errors = [];
+		const file = 'hdocbook-project.json';
+
+		check_extra_keys(config, project_top_keys, '', file, errors);
+
+		if (!config.docId || typeof config.docId !== 'string') {
+			errors.push(`${file}: "docId" is required and must be a string`);
+		} else if (!regex_doc_id.test(config.docId)) {
+			errors.push(`${file}: "docId" must use kebab-case (lowercase letters, numbers, hyphens): "${config.docId}"`);
+		}
+
+		if (config.pdfGeneration !== undefined) {
+			if (typeof config.pdfGeneration !== 'object' || Array.isArray(config.pdfGeneration)) {
+				errors.push(`${file}: "pdfGeneration" must be an object`);
+			} else {
+				check_extra_keys(config.pdfGeneration, project_pdf_keys, 'pdfGeneration', file, errors);
+				if (config.pdfGeneration.enable === undefined) {
+					errors.push(`${file}: "pdfGeneration.enable" is required`);
+				} else if (typeof config.pdfGeneration.enable !== 'boolean') {
+					errors.push(`${file}: "pdfGeneration.enable" must be a boolean`);
+				}
+				if (config.pdfGeneration.exclude_paths !== undefined) {
+					if (!Array.isArray(config.pdfGeneration.exclude_paths)) {
+						errors.push(`${file}: "pdfGeneration.exclude_paths" must be an array`);
+					} else {
+						for (let i = 0; i < config.pdfGeneration.exclude_paths.length; i++) {
+							if (typeof config.pdfGeneration.exclude_paths[i] !== 'string') {
+								errors.push(`${file}: "pdfGeneration.exclude_paths[${i}]" must be a string`);
+							}
+						}
+					}
+				}
+			}
+		}
+
+		if (config.validation !== undefined) {
+			if (typeof config.validation !== 'object' || Array.isArray(config.validation)) {
+				errors.push(`${file}: "validation" must be an object`);
+			} else {
+				check_extra_keys(config.validation, project_validation_keys, 'validation', file, errors);
+				if (config.validation.exclude_links !== undefined) {
+					if (!Array.isArray(config.validation.exclude_links)) {
+						errors.push(`${file}: "validation.exclude_links" must be an array`);
+					} else {
+						for (let i = 0; i < config.validation.exclude_links.length; i++) {
+							if (typeof config.validation.exclude_links[i] !== 'string') {
+								errors.push(`${file}: "validation.exclude_links[${i}]" must be a string`);
+							}
+						}
+					}
+				}
+				if (config.validation.exclude_spellcheck !== undefined) {
+					if (!Array.isArray(config.validation.exclude_spellcheck)) {
+						errors.push(`${file}: "validation.exclude_spellcheck" must be an array`);
+					} else {
+						for (let i = 0; i < config.validation.exclude_spellcheck.length; i++) {
+							const item = config.validation.exclude_spellcheck[i];
+							if (typeof item !== 'object' || Array.isArray(item) || item === null) {
+								errors.push(`${file}: "validation.exclude_spellcheck[${i}]" must be an object`);
+							} else {
+								check_extra_keys(item, ['document_path', 'words'], `validation.exclude_spellcheck[${i}]`, file, errors);
+								if (!item.document_path || typeof item.document_path !== 'string') {
+									errors.push(`${file}: "validation.exclude_spellcheck[${i}].document_path" is required and must be a non-empty string`);
+								}
+								if (!Array.isArray(item.words)) {
+									errors.push(`${file}: "validation.exclude_spellcheck[${i}].words" is required and must be an array`);
+								} else {
+									for (let j = 0; j < item.words.length; j++) {
+										if (typeof item.words[j] !== 'string') {
+											errors.push(`${file}: "validation.exclude_spellcheck[${i}].words[${j}]" must be a string`);
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+				if (config.validation.exclude_h1_count !== undefined) {
+					if (!Array.isArray(config.validation.exclude_h1_count)) {
+						errors.push(`${file}: "validation.exclude_h1_count" must be an array`);
+					} else {
+						for (let i = 0; i < config.validation.exclude_h1_count.length; i++) {
+							if (typeof config.validation.exclude_h1_count[i] !== 'string') {
+								errors.push(`${file}: "validation.exclude_h1_count[${i}]" must be a string`);
+							}
+						}
+					}
+				}
+				if (config.validation.external_link_warnings !== undefined &&
+					typeof config.validation.external_link_warnings !== 'boolean') {
+					errors.push(`${file}: "validation.external_link_warnings" must be a boolean`);
+				}
+			}
+		}
+
+		if (config.redirects !== undefined) {
+			if (!Array.isArray(config.redirects)) {
+				errors.push(`${file}: "redirects" must be an array`);
+			} else {
+				for (let i = 0; i < config.redirects.length; i++) {
+					const r = config.redirects[i];
+					if (typeof r !== 'object' || Array.isArray(r) || r === null) {
+						errors.push(`${file}: "redirects[${i}]" must be an object`);
+					} else {
+						check_extra_keys(r, project_redirect_keys, `redirects[${i}]`, file, errors);
+						if (!r.url || typeof r.url !== 'string') {
+							errors.push(`${file}: "redirects[${i}].url" is required and must be a non-empty string`);
+						}
+						if (r.code === undefined) {
+							errors.push(`${file}: "redirects[${i}].code" is required`);
+						} else if (!redirect_valid_codes.includes(r.code)) {
+							errors.push(`${file}: "redirects[${i}].code" must be ${redirect_valid_codes.join(', ')} (got ${r.code})`);
+						}
+						if (r.location !== undefined && typeof r.location !== 'string') {
+							errors.push(`${file}: "redirects[${i}].location" must be a string`);
+						}
+						if (r.skip_location_validation !== undefined && typeof r.skip_location_validation !== 'boolean') {
+							errors.push(`${file}: "redirects[${i}].skip_location_validation" must be a boolean`);
+						}
+					}
+				}
+			}
+		}
+
+		return errors;
+	};
+
+	// Validates the structure of hdocbook.json
+	const validate_book = (config, expected_doc_id) => {
+		const errors = [];
+		const file = 'hdocbook.json';
+
+		check_extra_keys(config,
+			['docId', 'title', 'description', 'publicSource', 'version', 'productFamily',
+			 'coverImage', 'tags', 'audience', 'languages', 'readingTime', 'navigation', 'inline'],
+			'', file, errors);
+
+		if (!config.docId || typeof config.docId !== 'string') {
+			errors.push(`${file}: "docId" is required and must be a string`);
+		} else {
+			if (!regex_doc_id.test(config.docId)) {
+				errors.push(`${file}: "docId" must use kebab-case (lowercase letters, numbers, hyphens): "${config.docId}"`);
+			}
+			if (expected_doc_id && config.docId !== expected_doc_id) {
+				errors.push(`${file}: "docId" value "${config.docId}" does not match the folder name and the docId in hdocbook-project.json ("${expected_doc_id}")`);
+			}
+		}
+
+		if (!config.title || typeof config.title !== 'string') {
+			errors.push(`${file}: "title" is required and must be a non-empty string`);
+		}
+
+		if (!config.version || typeof config.version !== 'string') {
+			errors.push(`${file}: "version" is required and must be a string`);
+		} else if (!regex_version.test(config.version)) {
+			errors.push(`${file}: "version" must be in X.Y.Z format (got "${config.version}")`);
+		}
+
+		if (!config.productFamily || typeof config.productFamily !== 'string') {
+			errors.push(`${file}: "productFamily" is required and must be a string`);
+		} else if (!valid_product_families.includes(config.productFamily)) {
+			errors.push(`${file}: "productFamily" value "${config.productFamily}" is not recognised. Valid values: ${valid_product_families.join(', ')}`);
+		}
+
+		if (!config.audience || !Array.isArray(config.audience) || config.audience.length === 0) {
+			errors.push(`${file}: "audience" is required and must be a non-empty array`);
+		} else {
+			for (let i = 0; i < config.audience.length; i++) {
+				if (typeof config.audience[i] !== 'string') {
+					errors.push(`${file}: "audience[${i}]" must be a string`);
+				} else if (!valid_audience.includes(config.audience[i])) {
+					errors.push(`${file}: "audience[${i}]" value "${config.audience[i]}" is not recognised. Valid values: ${valid_audience.join(', ')}`);
+				}
+			}
+		}
+
+		if (!config.navigation || typeof config.navigation !== 'object' || Array.isArray(config.navigation)) {
+			errors.push(`${file}: "navigation" is required and must be an object`);
+		} else {
+			check_extra_keys(config.navigation, ['items'], 'navigation', file, errors);
+			if (!Array.isArray(config.navigation.items)) {
+				errors.push(`${file}: "navigation.items" is required and must be an array`);
+			} else if (config.navigation.items.length === 0) {
+				errors.push(`${file}: "navigation.items" must not be empty`);
+			} else {
+				for (let i = 0; i < config.navigation.items.length; i++) {
+					validate_nav_item(config.navigation.items[i], `navigation.items[${i}]`, errors, 1);
+				}
+			}
+		}
+
+		if (config.description !== undefined && typeof config.description !== 'string') {
+			errors.push(`${file}: "description" must be a string`);
+		}
+
+		if (config.publicSource !== undefined && config.publicSource !== '') {
+			if (typeof config.publicSource !== 'string') {
+				errors.push(`${file}: "publicSource" must be a string`);
+			} else if (config.publicSource.toLowerCase() === '--publicsource--') {
+				errors.push(`${file}: "publicSource" is still set to its default template value`);
+			} else if (
+				!config.publicSource.startsWith('https://github.com') &&
+				!config.publicSource.startsWith('https://api.github.com')
+			) {
+				errors.push(`${file}: "publicSource" must be a GitHub URL starting with https://github.com or https://api.github.com (got "${config.publicSource}")`);
+			}
+		}
+
+		if (config.coverImage !== undefined && typeof config.coverImage !== 'string') {
+			errors.push(`${file}: "coverImage" must be a string`);
+		}
+
+		if (config.tags !== undefined) {
+			if (!Array.isArray(config.tags)) {
+				errors.push(`${file}: "tags" must be an array`);
+			} else {
+				for (let i = 0; i < config.tags.length; i++) {
+					if (typeof config.tags[i] !== 'string') {
+						errors.push(`${file}: "tags[${i}]" must be a string`);
+					}
+				}
+			}
+		}
+
+		if (config.languages !== undefined) {
+			if (!Array.isArray(config.languages)) {
+				errors.push(`${file}: "languages" must be an array`);
+			} else {
+				for (let i = 0; i < config.languages.length; i++) {
+					if (typeof config.languages[i] !== 'string') {
+						errors.push(`${file}: "languages[${i}]" must be a string`);
+					}
+				}
+			}
+		}
+
+		if (config.inline !== undefined) {
+			if (!Array.isArray(config.inline)) {
+				errors.push(`${file}: "inline" must be an array`);
+			} else {
+				for (let i = 0; i < config.inline.length; i++) {
+					const item = config.inline[i];
+					if (typeof item !== 'object' || Array.isArray(item) || item === null) {
+						errors.push(`${file}: "inline[${i}]" must be an object`);
+					} else {
+						check_extra_keys(item, ['title', 'link'], `inline[${i}]`, file, errors);
+						if (!item.title || typeof item.title !== 'string') {
+							errors.push(`${file}: "inline[${i}].title" is required and must be a non-empty string`);
+						}
+						if (!item.link || typeof item.link !== 'string') {
+							errors.push(`${file}: "inline[${i}].link" is required and must be a non-empty string`);
+						}
+					}
+				}
+			}
+		}
+
+		return errors;
+	};
+
+	exports.validate_project = validate_project;
+	exports.validate_book = validate_book;
+})();

package/hdoc.js

@@ -13,69 +13,98 @@
 
 	let console_color = true;
 
-	console.log = (...args) => {
-		if (process.env.GITHUB_ACTIONS !== 'true') {
-			// If not running in GitHub Actions, send args to the original console.log
-			originalConsoleLog(...args);
-			
-		} else {
-			// If running in GitHub Actions, escape % and \ characters so printf doesn't throw an error
-			const escapedArgs = args.map(arg => {
-				if (typeof arg === 'string') {
-					return arg.replace(/%/g, '%%').replace(/\\/g, '\\\\');
-				}
-				return arg;
-			});
-			// Use the original console.log with escaped arguments
-			originalConsoleLog(...escapedArgs);
-		}
-	};
+	// Quiet mode: suppress all output, show a spinner, print only errors (or success) at exit
+	const _quietMode = process.argv.includes('--quiet') && process.argv[2] === 'validate';
+	const _quietErrors = [];
+
+	if (_quietMode) {
+		const _spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+		let _spinnerIdx = 0;
+		const _spinnerInterval = setInterval(() => {
+			process.stderr.write(`\r${_spinnerFrames[_spinnerIdx++ % _spinnerFrames.length]} Validating...`);
+		}, 100);
+		_spinnerInterval.unref(); // Don't prevent natural process exit
 
-	if (process.env.GITHUB_ACTIONS === 'true') {
-		console.log("\nRunning in GitHub Actions environment\n");
+		console.log = () => {};
+		console.info = () => {};
+		console.error = (...args) => {
+			_quietErrors.push(args.map(a => (typeof a === 'string' ? a : String(a))).join(' '));
+		};
+
+		process.on('exit', (code) => {
+			clearInterval(_spinnerInterval);
+			process.stderr.write('\r\x1b[K');
+			if (_quietErrors.length > 0) {
+				for (const e of _quietErrors) originalConsoleError(`${e}\n`);
+			} else if (code === 0) {
+				originalConsoleLog('No validation errors found');
+			}
+		});
 	} else {
-		console.log("\nRunning in non-GitHub Actions environment\n");
-	}
+		console.log = (...args) => {
+			if (process.env.GITHUB_ACTIONS !== 'true') {
+				// If not running in GitHub Actions, send args to the original console.log
+				originalConsoleLog(...args);
 
-	console.info = (...args) => {
+			} else {
+				// If running in GitHub Actions, escape % and \ characters so printf doesn't throw an error
+				const escapedArgs = args.map(arg => {
+					if (typeof arg === 'string') {
+						return arg.replace(/%/g, '%%').replace(/\\/g, '\\\\');
+					}
+					return arg;
+				});
+				// Use the original console.log with escaped arguments
+				originalConsoleLog(...escapedArgs);
+			}
+		};
 
-		if (process.env.GITHUB_ACTIONS !== 'true') {
-			// If not running in GitHub Actions, send args to the original console.log
-			if (console_color) originalConsoleInfo(`\x1b[33m${args}\x1b[0m`);
-			else originalConsoleInfo(...args);
+		if (process.env.GITHUB_ACTIONS === 'true') {
+			console.log("\nRunning in GitHub Actions environment\n");
 		} else {
-			// If running in GitHub Actions, escape % and \ characters so printf doesn't throw an error
-			const escapedArgs = args.map(arg => {
-				if (typeof arg === 'string') {
-					return arg.replace(/%/g, '%%').replace(/\\/g, '\\\\');
-				}
-				return arg;
-			});
-			// Use the original console.log with escaped arguments
-			originalConsoleInfo(...escapedArgs);
+			console.log("\nRunning in non-GitHub Actions environment\n");
 		}
 
-	};
+		console.info = (...args) => {
 
-	console.error = (...args) => {
+			if (process.env.GITHUB_ACTIONS !== 'true') {
+				// If not running in GitHub Actions, send args to the original console.log
+				if (console_color) originalConsoleInfo(`\x1b[33m${args}\x1b[0m`);
+				else originalConsoleInfo(...args);
+			} else {
+				// If running in GitHub Actions, escape % and \ characters so printf doesn't throw an error
+				const escapedArgs = args.map(arg => {
+					if (typeof arg === 'string') {
+						return arg.replace(/%/g, '%%').replace(/\\/g, '\\\\');
+					}
+					return arg;
+				});
+				// Use the original console.log with escaped arguments
+				originalConsoleInfo(...escapedArgs);
+			}
 
-		if (process.env.GITHUB_ACTIONS !== 'true') {
-			// If not running in GitHub Actions, send args to the original console.log
-			if (console_color) originalConsoleError(`\x1b[33m${args}\x1b[0m`);
-			else originalConsoleError(...args);
-		} else {
+		};
 
-			// If running in GitHub Actions, escape % and \ characters so printf doesn't throw an error
-			const escapedArgs = args.map(arg => {
-				if (typeof arg === 'string') {
-					return arg.replace(/%/g, '%%').replace(/\\/g, '\\\\');
-				}
-				return arg;
-			});
-			// Use the original console.log with escaped arguments
-			originalConsoleError(...escapedArgs);
-		}
-	};
+		console.error = (...args) => {
+
+			if (process.env.GITHUB_ACTIONS !== 'true') {
+				// If not running in GitHub Actions, send args to the original console.log
+				if (console_color) originalConsoleError(`\x1b[33m${args}\x1b[0m`);
+				else originalConsoleError(...args);
+			} else {
+
+				// If running in GitHub Actions, escape % and \ characters so printf doesn't throw an error
+				const escapedArgs = args.map(arg => {
+					if (typeof arg === 'string') {
+						return arg.replace(/%/g, '%%').replace(/\\/g, '\\\\');
+					}
+					return arg;
+				});
+				// Use the original console.log with escaped arguments
+				originalConsoleError(...escapedArgs);
+			}
+		};
+	}
 
 	const getHdocPackageVersion = (packagePath) => {
 		if (fs.existsSync(packagePath)) {
@@ -105,6 +134,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 +181,10 @@
 			console_color = false;
 		} else if (process.argv[x].toLowerCase() === "--no-links") {
 			output_links = false;
+		} else if (process.argv[x].toLowerCase() === "--onyx") {
+			onyx_index = true;
+		} else if (process.argv[x].toLowerCase() === "--quiet") {
+			// handled at startup via _quietMode
 		}
 	}
 	source_path = hdoc.true_case_path_sync(source_path);
@@ -186,6 +220,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 +235,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.5",
+	"version": "0.50.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",
@@ -20,10 +21,12 @@
 		"hdoc-serve.js",
 		"hdoc-stats.js",
 		"hdoc-validate.js",
+		"hdoc-validate-config.js",
 		"hdoc-ver.js",
 		"validateNodeVer.js",
 		"ui",
 		"custom_modules",
+		"schemas",
 		"templates",
 		"templates/init/.npmignore",
 		"templates/init/gitignore",

package/schemas/hdocbook-project.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "hdocbook-project.schema.json",
+  "title": "HDocBook Project Configuration",
+  "description": "Schema for hdocbook-project.json - project-level build and validation configuration",
+  "type": "object",
+  "required": ["docId"],
+  "additionalProperties": false,
+  "properties": {
+    "docId": {
+      "type": "string",
+      "description": "The document ID. Must match the book folder name and use kebab-case.",
+      "pattern": "^[a-z][a-z0-9-]+$"
+    },
+    "pdfGeneration": {
+      "type": "object",
+      "description": "Controls PDF generation during the book build.",
+      "required": ["enable"],
+      "additionalProperties": false,
+      "properties": {
+        "enable": {
+          "type": "boolean",
+          "description": "Whether to generate PDFs for page content during the build."
+        },
+        "exclude_paths": {
+          "type": "array",
+          "description": "Paths to exclude from PDF generation. Supports a trailing * wildcard.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "description": "Controls book validation behaviour.",
+      "additionalProperties": false,
+      "properties": {
+        "exclude_links": {
+          "type": "array",
+          "description": "Links to skip during link validation. Supports a trailing * wildcard.",
+          "items": { "type": "string" }
+        },
+        "exclude_spellcheck": {
+          "type": "array",
+          "description": "Per-document spellcheck word exclusions.",
+          "items": {
+            "type": "object",
+            "required": ["document_path", "words"],
+            "additionalProperties": false,
+            "properties": {
+              "document_path": {
+                "type": "string",
+                "description": "Root-relative path to the document, without file extension."
+              },
+              "words": {
+                "type": "array",
+                "description": "Words to exclude from the British English spellcheck for this document.",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        },
+        "exclude_h1_count": {
+          "type": "array",
+          "description": "Root-relative paths of documents allowed to have more than one H1 tag.",
+          "items": { "type": "string" }
+        },
+        "external_link_warnings": {
+          "type": "boolean",
+          "description": "When true, external link failures are reported as warnings rather than errors."
+        }
+      }
+    },
+    "redirects": {
+      "type": "array",
+      "description": "Permanent redirects for pages that have moved or been deleted.",
+      "items": {
+        "type": "object",
+        "required": ["url", "code"],
+        "additionalProperties": false,
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "The path being redirected from."
+          },
+          "code": {
+            "type": "integer",
+            "description": "HTTP redirect code. 301 = moved permanently, 308 = permanent redirect, 410 = gone.",
+            "enum": [301, 308, 410]
+          },
+          "location": {
+            "type": "string",
+            "description": "Destination path for 301/308 redirects. Not applicable for 410."
+          },
+          "skip_location_validation": {
+            "type": "boolean",
+            "description": "Skip validation of the redirect destination path."
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/hdocbook.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "hdocbook.schema.json",
+  "title": "HDocBook Configuration",
+  "description": "Schema for hdocbook.json - book metadata, navigation, and publishing configuration",
+  "type": "object",
+  "required": ["docId", "title", "description", "version", "productFamily", "audience", "navigation"],
+  "additionalProperties": false,
+  "properties": {
+    "docId": {
+      "type": "string",
+      "description": "The unique document ID. Must match the folder name that contains this file, using kebab-case.",
+      "pattern": "^[a-z][a-z0-9-]+$"
+    },
+    "title": {
+      "type": "string",
+      "description": "The full title of the book as presented without other context."
+    },
+    "description": {
+      "type": "string",
+      "description": "A short description of the book's purpose and contents."
+    },
+    "publicSource": {
+      "type": "string",
+      "description": "URL to the public GitHub repository for this book. Omit or leave empty for private books.",
+      "pattern": "^https://(github\\.com|api\\.github\\.com)/"
+    },
+    "version": {
+      "type": "string",
+      "description": "Book version in X.Y.Z format. Controls automated publishing — increment to trigger a new publish.",
+      "pattern": "^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,6}$"
+    },
+    "productFamily": {
+      "type": "string",
+      "description": "The ID of the product family this book belongs to.",
+      "enum": [
+        "esp",
+        "com.hornbill.docmanager",
+        "com.hornbill.boardmanager",
+        "com.hornbill.customermanager",
+        "com.hornbill.grc",
+        "com.hornbill.itom",
+        "com.hornbill.livechat",
+        "com.hornbill.projectmanager",
+        "com.hornbill.servicemanager",
+        "com.hornbill.suppliermanager",
+        "com.hornbill.timesheetmanager",
+        "com.hornbill.collaboration",
+        "appdev",
+        "hdocs"
+      ]
+    },
+    "coverImage": {
+      "type": "string",
+      "description": "Root-relative path to a cover image used for gallery and social sharing. Optional."
+    },
+    "tags": {
+      "type": "array",
+      "description": "Tags associated with this book.",
+      "items": { "type": "string" }
+    },
+    "audience": {
+      "type": "array",
+      "description": "Target audiences for this book. At least one value is required.",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "public",
+          "private",
+          "private.cloud",
+          "private.dev.platform",
+          "private.dev.apps",
+          "private.hdocs",
+          "private.elearning"
+        ]
+      }
+    },
+    "languages": {
+      "type": "array",
+      "description": "Language codes for the languages available in this book (e.g. 'en').",
+      "items": { "type": "string" }
+    },
+    "readingTime": {
+      "type": "number",
+      "description": "Total estimated reading time in minutes. Calculated and written automatically during build — do not set manually."
+    },
+    "navigation": {
+      "type": "object",
+      "description": "Defines the navigation tree displayed alongside book content.",
+      "required": ["items"],
+      "additionalProperties": false,
+      "properties": {
+        "items": {
+          "type": "array",
+          "description": "Top-level navigation items. Maximum three levels of nesting are supported.",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/navigationItem" }
+        }
+      }
+    },
+    "inline": {
+      "type": "array",
+      "description": "Inline content sources — content embedded from other books.",
+      "items": {
+        "type": "object",
+        "required": ["title", "link"],
+        "additionalProperties": false,
+        "properties": {
+          "title": { "type": "string" },
+          "link": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "navigationItem": {
+      "type": "object",
+      "required": ["text"],
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "description": "Display text for the navigation item."
+        },
+        "link": {
+          "type": "string",
+          "description": "Path to the content page. Ignored when 'items' is present."
+        },
+        "expand": {
+          "type": "boolean",
+          "description": "Whether this item is expanded by default."
+        },
+        "draft": {
+          "type": "boolean",
+          "description": "When true, this item is excluded from published output."
+        },
+        "items": {
+          "type": "array",
+          "description": "Child navigation items.",
+          "items": { "$ref": "#/$defs/navigationItem" }
+        }
+      }
+    }
+  }
+}