hdoc-tools 0.39.1 → 0.41.0

package/hdoc-build.js

@@ -13,6 +13,9 @@
 	const archiver = require("archiver");
 	const xmlFormat = require("xml-formatter");
 
+	const { execSync } = require("child_process");
+	const tmp = require("tmp");
+
 	const h_tags_to_search = ["h1", "h2", "h3"];
 	const image_extensions = ["png", "svg", "jpg"];
 	const doc_header_template_path = path.join(
@@ -35,6 +38,13 @@
 		"templates",
 		"pdf-header-non-git.html",
 	);
+
+	const mermaid_theme_path = path.resolve(
+		__dirname,
+		"templates",
+		"mermaid-theme.yaml",
+	);
+
 	const pdf_template_path = path.join(__dirname, "templates", "pdf");
 	const ui_css_path = path.join(__dirname, "ui", "css");
 	const pdf_template_file_path = path.join(pdf_template_path, "template.html");
@@ -52,6 +62,7 @@
 	const md_files_delete = [];
 	const redirects = {};
 	const static_html_files = [];
+	const mermaid_failures = [];
 
 	let bc = {}; // Breadcrumbs map
 	let book_read_time = 0;
@@ -508,6 +519,38 @@
 				html: true,
 				linkify: true,
 				typographer: true,
+				highlight: function (str, lang) {
+					if (lang === "mermaid") {
+						try {
+							const tmpInput = tmp.fileSync({ postfix: ".mmd" });
+							const tmpOutput = tmp.fileSync({ postfix: ".svg" });
+
+							if (!str.startsWith('---')) {
+								str = '---\n' + fs.readFileSync(mermaid_theme_path, {encoding: 'utf-8'}) + `\n---\n${str}`;
+							}
+
+							fs.writeFileSync(tmpInput.name, str);
+
+							const cmd = `${__dirname}/node_modules/.bin/mmdc -i "${tmpInput.name}" -o "${tmpOutput.name}" --quiet --backgroundColor transparent"`;
+							console.log(`Generating Inline Mermaid SVG found in: ${file_path.relativePath}`);
+							execSync(cmd);
+							
+							if (!fs.existsSync(tmpOutput.name)) {
+								throw new Error("mmdc did not generate output");
+							}
+
+							const svg = fs.readFileSync(tmpOutput.name, "utf8");
+
+							tmpInput.removeCallback();
+							tmpOutput.removeCallback();
+
+							return `<div class="text-body">${svg}</div>`;
+						} catch (err) {
+							mermaid_failures.push({path: file_path.relativePath, error: err.message});
+							return  ``;
+						}
+					}
+				}
 			});
 			md.linkify.set({
 				fuzzyEmail: false,
@@ -1396,6 +1439,21 @@
 			console.log(`             PDF Files Created: ${pdf_created}\n`);
 		}
 
+
+		if (mermaid_failures.length > 0) {			
+			console.log("\r\n-----------------------");
+			console.log("   Validation Output   ");
+			console.log("-----------------------");
+			console.log(
+				`\n${mermaid_failures.length} errors found when processing markdown SVG generation:\n`,
+			);
+			for (const key in mermaid_failures) {
+				console.error(` - ${mermaid_failures[key].path}:\n${mermaid_failures[key].error}`);
+			}
+			console.log("\n");
+			process.exit(1);
+		}
+
 		// Validate content
 		const validation_success = await hdoc_validate.run(
 			work_path,

package/hdoc-serve.js

@@ -6,7 +6,16 @@
 	const stream = require("node:stream");
 
 	const yaml = require("js-yaml");
-	const mdfm = require("markdown-it-front-matter");
+	const mdfm = require("markdown-it-front-matter");						
+
+	const { execSync } = require("child_process");
+	const tmp = require("tmp");
+
+	const mermaid_theme_path = path.resolve(
+		__dirname,
+		"templates",
+		"mermaid-theme.yaml",
+	);
 
 	let port = 3000;
 	let docId;
@@ -105,78 +114,98 @@
 		});
 
 		async function transform_markdown_and_send_html(req, res, file_path) {
-			if (fs.existsSync(file_path)) {
-				// we have a markdown representation of the requested HTML file, transform and return
-				// it to the caller
-
-				// Load markdown file
-				let md_txt = hdoc.expand_variables(
-					fs.readFileSync(file_path).toString(),
-					docId,
-				);
-
-				// Pull in external includes
-				const includes_processed = await hdoc.process_includes(
-					file_path,
-					md_txt,
-					global_source_path,
-				);
-				md_txt = includes_processed.body;
-				if (includes_processed.errors && includes_processed.errors.length > 0) {
-					console.error(`Error(s) when processing includes in ${file_path}`);
-					for (let i = 0; i < includes_processed.errors.length; i++) {
-						console.error(includes_processed.errors[i]);
-					}
-				} else {
-					if (includes_processed.success > 0) {
-						console.log(
-							`Includes injected into document: ${includes_processed.success}`,
-						);
-					}
-				}
-
-				const md = require("markdown-it")({
-					// enable everything
-					html: true,
-					linkify: true,
-					typographer: true,
-				});
+			if (!fs.existsSync(file_path)) return false;
 
-				md.linkify.set({
-					fuzzyEmail: false,
-					fuzzyLink: false,
-					fuzzyIP: false,
-				});
-				let frontmatter_content = "";
-				md.use(mdfm, (fm) => {
-					frontmatter_content = fm;
-				});
-
-				const tips = require(`${__dirname}/custom_modules/tips.js`);
-				md.use(tips, {
-					links: true,
-				});
-
-				// Render markdown into HTML
-				const html_txt = md.render(md_txt.toString());
+			let md_txt = hdoc.expand_variables(
+				fs.readFileSync(file_path).toString(),
+				docId,
+			);
 
-				if (frontmatter_content.length) {
-					const obj = yaml.load(frontmatter_content);
+			const includes_processed = await hdoc.process_includes(
+				file_path,
+				md_txt,
+				global_source_path,
+			);
+			md_txt = includes_processed.body;
+			const md = require("markdown-it")({
+				html: true,
+				linkify: true,
+				typographer: true,
+				highlight: function (str, lang) {
+					if (lang === "mermaid") {
+						try {
+							const tmpInput = tmp.fileSync({ postfix: ".mmd" });
+							const tmpOutput = tmp.fileSync({ postfix: ".svg" });
+
+							if (!str.startsWith('---')) {
+								str = '---\n' + fs.readFileSync(mermaid_theme_path, {encoding: 'utf-8'}) + `\n---\n${str}`;
+							}
+
+							fs.writeFileSync(tmpInput.name, str);
+
+							const cmd = `${__dirname}/node_modules/.bin/mmdc -i "${tmpInput.name}" -o "${tmpOutput.name}" --quiet --backgroundColor transparent"`;
+							console.log(`Generating Inline Mermaid SVG found in: ${file_path}`);
+							execSync(cmd);
+
+							if (!fs.existsSync(tmpOutput.name)) {
+								throw new Error("mmdc did not generate output");
+							}
+
+							const svg = fs.readFileSync(tmpOutput.name, "utf8");
+
+							tmpInput.removeCallback();
+							tmpOutput.removeCallback();
+
+							return `<div class="text-body">${svg}</div>`;
+						} catch (err) {
+							return  `<div class="alert alert-danger mb-0 text-break" 
+role="alert"
+data-bs-toggle="collapse" 
+data-bs-target="#alertContent" 
+aria-expanded="false" 
+aria-controls="alertContent">
+<div>
+<strong>Error!</strong> Mermaid was unable to generate the SVG expected here. Click for more details
+</div>
+<div class="collapse mt-3" id="alertContent">
+<p class="mb-0 text-break">
+${err.message}
+</p>
+</div>
+</div>`;
+						}
+					}
+				}
+			});
+			md.linkify.set({
+				fuzzyEmail: false,
+				fuzzyLink: false,
+				fuzzyIP: false,
+			});
 
-					const buff = Buffer.from(JSON.stringify(obj), "utf-8");
+			let frontmatter_content = "";
+			md.use(mdfm, (fm) => {
+				frontmatter_content = fm;
+			});
 
-					const base64 = buff.toString("base64");
+			const tips = require(`${__dirname}/custom_modules/tips.js`);
+			md.use(tips, { links: true });
 
-					res.setHeader("X-frontmatter", base64);
-				}
+			const html_txt = md.render(md_txt.toString());
 
-				res.setHeader("Content-Type", "text/html");
-				res.send(html_txt);
-				return true;
+			if (frontmatter_content.length) {
+				const obj = yaml.load(frontmatter_content);
+				const buff = Buffer.from(JSON.stringify(obj), "utf-8");
+				const base64 = buff.toString("base64");
+				res.setHeader("X-frontmatter", base64);
 			}
-			return false;
+
+			res.setHeader("Content-Type", "text/html");
+			res.send(html_txt);
+			return true;
 		}
 
+
 		function send_content_file(req, res, file_path, redirected = false) {
 			let content_txt = hdoc.expand_variables(
 				fs.readFileSync(file_path).toString(),
@@ -386,4 +415,5 @@
 			}
 		});
 	};
+
 })();

package/hdoc-validate.js

@@ -10,6 +10,7 @@ const e = require("express");
 	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
 	const translator = require("american-british-english-translator");
 	const { trueCasePathSync } = require("true-case-path");
+	const puppeteer = require("puppeteer");
 
 	const spellcheck_options = {
 		british: true,
@@ -470,15 +471,14 @@ const e = require("express");
 		const markdown_paths = getMDPathFromHtmlPath(htmlFile);
 		const markdown_content = fs.readFileSync(markdown_paths.markdownPath, 'utf8');
 
-		// Use Puppeteer to validate link address works
-		const page = await browser.newPage();
-
+		
 		for (let i = 0; i < links.length; i++) {
 			// Validate that link is a valid URL first
-			if (exclude_links[links[i]]) continue;
 			console.log(` - ${links[i]}`);
+			if (exclude_links[links[i]]) continue;
 			if (global_links_checked.includes(links[i])) continue;
 			global_links_checked.push(links[i]);
+			
 			const valid_url = hdoc.valid_url(links[i]);
 			if (!valid_url) {
 				// Could be a relative path, check
@@ -585,6 +585,8 @@ const e = require("express");
 					continue;
 				}
 
+				// Use Puppeteer to validate link address works
+				const page = await browser.newPage();
 
 				try {
 					// Set a user-agent to mimic a real browser
@@ -610,9 +612,7 @@ const e = require("express");
 						});
 
 						// Try loading the URL
-						response = await page.goto(links[i], { waitUntil: 'networkidle2' }).catch(() => {
-							// Ignore rendering errors (likely binary files like PDFs)
-						});
+						response = await page.goto(links[i], { waitUntil: 'networkidle2', timeout: 10000 });
 
 						if (response) {
 							let status = response.status();
@@ -626,7 +626,7 @@ const e = require("express");
 								}, links[i]);
 							}
 							if ((status < 200 || status > 299) && status !== 304) {
-								if (status === 403 && links[i].includes(".hornbill.com")) {
+								if (process.env.GITHUB_ACTIONS === 'true' && status === 403 && links[i].includes(".hornbill.com")) {
 									// STEVEG - do nothing here, as it always returns a 403 for Hornbill sites when accessing through GitHub Actions
 									// Works totally fine locally or in hdocpub, still trying to work out what's causing this in GitHub
 								} else {
@@ -648,16 +648,16 @@ const e = require("express");
 					} else {
 						error_message = processErrorMessage(`Issue with external link [${links[i]}]: ${e}`, markdown_paths.relativePath, markdown_content, links[i]);
 					}
-					if (hdocbook_project.validation.external_link_warnings)
+					if (hdocbook_project.validation.external_link_warnings || process.env.GITHUB_ACTIONS === 'true')
 						warnings[htmlFile.relativePath].push(error_message);
 					else
 						errors[htmlFile.relativePath].push(error_message);
 					
 				}
+				// Close the headless browser tab
+				page.close();
 			}
 		}
-		// Close the headless browser tab
-		page.close();
 	};
 
 	const checkHostExistsInDNS = async (hostname) => {
@@ -1060,7 +1060,8 @@ const e = require("express");
 
 		
 		const global_links_checked = [];
-
+		const validateBrowser = await puppeteer.launch({ args: ['--no-sandbox'] });
+		
 		for (const key in html_to_validate) {
 			const file = html_to_validate[key];
 			// Check for British spellings in static HTML content
@@ -1085,7 +1086,7 @@ const e = require("express");
 				messages[file.relativePath].push("No links found in file");
 			} else {
 				console.log(`\r\nChecking Links in ${file.relativePath}`);
-				await checkLinks(source_path, file, links.href, hdocbook_config, hdocbook_project, browser, global_links_checked);
+				await checkLinks(source_path, file, links.href, hdocbook_config, hdocbook_project, validateBrowser, global_links_checked);
 			}
 			if (links.img.length === 0) {
 				messages[file.relativePath].push("No images found in file");
@@ -1096,6 +1097,9 @@ const e = require("express");
 			// Check for multiple H1 tags
 			await checkTags(file);
 		}
+
+		// Close the Chromium browser instance
+		await validateBrowser.close();
 		
 		if (gen_exclude) console.log(JSON.stringify(excl_output, null, 2));
 

package/hdoc.js

@@ -8,6 +8,10 @@
 	const packageFile = path.join(__dirname, "package.json");
 
 	const originalConsoleLog = console.log;
+	const originalConsoleError = console.error;
+	const originalConsoleInfo = console.info;
+
+	let console_color = true;
 
 	console.log = (...args) => {
 		if (process.env.GITHUB_ACTIONS !== 'true') {
@@ -33,18 +37,44 @@
 		console.log("\nRunning in non-GitHub Actions environment\n");
 	}
 
-	let console_color = true;
+	console.info = (...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);
+		}
 
-	const { info, error } = console;
-	console.info = (arg) => {
-		if (console_color)
-			info.call(console, `\x1b[33m${arg}\x1b[0m`);
-		else info.call(console, arg);
 	};
-	console.error = (arg) => {
-		if (console_color)
-			error.call(console, `\x1b[31m${arg}\x1b[0m`);
-		else error.call(console, arg);
+
+	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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.39.1",
+	"version": "0.41.0",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {
@@ -51,10 +51,12 @@
 		"markdown-it": "14.1.0",
 		"markdown-it-container": "^4.0.0",
 		"markdown-it-front-matter": "^0.2.4",
+		"@mermaid-js/mermaid-cli": "11.6.0",
 		"mime-types": "^2.1.35",
 		"prompt": "^1.3.0",
-		"puppeteer": "^22.12.1",
+		"puppeteer": "^23.11.1",
 		"stream": "0.0.3",
+		"tmp": "^0.2.3",
 		"true-case-path": "^2.2.1",
 		"words-count": "^2.0.2",
 		"xml-formatter": "^3.6.2"

package/templates/mermaid-theme.yaml

@@ -0,0 +1,28 @@
+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