hdoc-tools 0.48.0 → 0.50.0

package/hdoc-build.js

@@ -5,6 +5,7 @@
 	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"));
@@ -977,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 (
@@ -1007,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;
@@ -1018,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)) {
@@ -154,6 +183,8 @@
 			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);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.48.0",
+	"version": "0.50.0",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {
@@ -21,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" }
+        }
+      }
+    }
+  }
+}