hdoc-tools 0.62.3 → 0.62.5

package/hdoc-install-browser.js

@@ -61,6 +61,30 @@
 
 	const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+	// @puppeteer/browsers mkdirs <cacheDir>/<browser> non-recursively, so the
+	// cache dir must exist first — on a fresh checkout it does not. A dangling
+	// symlink (e.g. left behind after the package dir it pointed at was removed)
+	// is worse: mkdir through it fails ENOENT forever, so drop it first.
+	try {
+		fs.lstatSync(cacheDir);
+		try {
+			fs.statSync(cacheDir); // resolves the link target
+		} catch {
+			log(`Removing dangling cache dir link: ${cacheDir}`);
+			fs.unlinkSync(cacheDir);
+		}
+	} catch {
+		/* nothing there yet */
+	}
+	try {
+		fs.mkdirSync(cacheDir, { recursive: true });
+	} catch (err) {
+		console.error(
+			`${RED}Unable to create browser cache dir ${cacheDir}: ${err.message}${RESET}`,
+		);
+		process.exit(1);
+	}
+
 	const rmrf = (target) => {
 		try {
 			fs.rmSync(target, { recursive: true, force: true });

package/hdoc-validate-interbook.js

@@ -290,6 +290,14 @@
 		const doc_id = segments.shift();
 		const article_path = segments.length > 0 ? segments.join("/") : "index";
 
+		// No book in the path (e.g. a bare "/") - nothing to resolve
+		if (!doc_id) {
+			return {
+				level: "skip",
+				message: `Inter-book link has no target book - link not verified: ${link}`,
+			};
+		}
+
 		// Books not sourced from GitHub — resolved by docId suffix, no repo
 		if (has_suffix(doc_id, UNVERIFIABLE_SUFFIXES)) {
 			return {

package/hdoc-validate.js

@@ -498,10 +498,22 @@
 		return resp.status;
 	};
 
-	// Map an inter-book check result onto errors/warnings/messages and the
-	// validated-links cache. 'ok' and 'skip' outcomes are stable, so they are
-	// appended to validated-links.txt like any other passing link.
-	const handleInterbookResult = (result, link, htmlFile, markdown_paths, markdown_content) => {
+	// Links already written to validated-links.txt this run. A link can appear
+	// on many pages, but only needs writing to the cache file once.
+	const skip_links_written = new Set();
+	const appendSkipLink = (link) => {
+		if (skip_links_written.has(link)) return;
+		skip_links_written.add(link);
+		fs.appendFileSync(skip_link_file, `${link}\n`);
+	};
+
+	// Map a network check result (inter-book or external URL) onto
+	// errors/warnings/messages and the validated-links cache. 'ok' and 'skip'
+	// outcomes are stable, so they are appended to validated-links.txt like any
+	// other passing link. Called once per PAGE carrying the link, so the
+	// message is positioned against the page being reported on.
+	const emitLinkResult = (result, link, htmlFile, markdown_paths, markdown_content) => {
+		if (!result) return;
 		if (result.level === "error") {
 			errors[htmlFile.relativePath].push(
 				processErrorMessage(result.message, markdown_paths.relativePath, markdown_content, link),
@@ -512,10 +524,25 @@
 			);
 		} else {
 			messages[htmlFile.relativePath].push(result.message);
-			fs.appendFileSync(skip_link_file, `${link}\n`);
+			appendSkipLink(link);
 		}
 	};
 
+	// Run a network check for a link at most once per run, but hand the SAME
+	// result back to every page that carries the link. Deduplicating the fetch
+	// is a performance concern; deduplicating the reporting is not - a broken
+	// link on ten pages has to be flagged on all ten, or fixing the first page
+	// just surfaces the second on the next build.
+	// global_links_checked: Map link -> Promise<{ level, message } | null>
+	const checkLinkOnce = (global_links_checked, link, check) => {
+		let pending = global_links_checked.get(link);
+		if (!pending) {
+			pending = check();
+			global_links_checked.set(link, pending);
+		}
+		return pending;
+	};
+
 	const checkLinks = async (source_path, htmlFile, links, hdocbook_config, hdocbook_project, global_links_checked, output_links) => {
 		const markdown_paths = getMDPathFromHtmlPath(htmlFile);
 		const markdown_content = fs.readFileSync(markdown_paths.markdownPath, 'utf8');
@@ -537,11 +564,15 @@
 		// concurrently rather than one-at-a-time.
 		const externalChecks = [];
 
+		// Same link twice on the same page is reported once. Across pages it is
+		// reported every time - see checkLinkOnce.
+		const page_links_checked = new Set();
+
 		for (let i = 0; i < links.length; i++) {
 			if (output_links) console.log(` - ${links[i]}`);
 			if (exclude_links[links[i]]) continue;
-			if (global_links_checked.includes(links[i])) continue;
-			global_links_checked.push(links[i]);
+			if (page_links_checked.has(links[i])) continue;
+			page_links_checked.add(links[i]);
 
 			const valid_url = hdoc.valid_url(links[i]);
 			if (!valid_url) {
@@ -554,6 +585,13 @@
 					if (link_segments[0] === "") link_segments.shift();
 					const link_root = link_segments[0] === "_books" ? link_segments[1] : link_segments[0];
 
+					// A bare "/" is the docs site home page - no book, nothing to
+					// resolve locally or against GitHub.
+					if (link_root === undefined || link_root === "") {
+						appendSkipLink(links[i]);
+						continue;
+					}
+
 					// Check for links with a _books path that have no specific file target
 					// We do need to exclude those with an extension though, for pages that link downloadable resources
 					if (link_segments[0] === "_books" && path.extname(links[i]) === '') {
@@ -567,8 +605,10 @@
 						if (interbook.enabled() && path.extname(links[i].split("#")[0]) === "") {
 							const link = links[i];
 							externalChecks.push(async () =>
-								handleInterbookResult(
-									await interbook.check_link(link),
+								emitLinkResult(
+									await checkLinkOnce(global_links_checked, link, () =>
+										interbook.check_link(link),
+									),
 									link,
 									htmlFile,
 									markdown_paths,
@@ -576,7 +616,7 @@
 								),
 							);
 						} else {
-							fs.appendFileSync(skip_link_file, `${links[i]}\n`);
+							appendSkipLink(links[i]);
 						}
 						continue;
 					}
@@ -603,12 +643,12 @@
 					)
 					.edit_path.replace(path.extname(htmlFile.relativePath), ".md")
 				) {
-					fs.appendFileSync(skip_link_file, `${links[i]}\n`);
+					appendSkipLink(links[i]);
 					continue;
 				}
 
 				if (valid_url.protocol === "mailto:") {
-					fs.appendFileSync(skip_link_file, `${links[i]}\n`);
+					appendSkipLink(links[i]);
 					continue;
 				}
 
@@ -653,8 +693,10 @@
 					const link = links[i];
 					const book_link = valid_url.pathname + valid_url.hash;
 					externalChecks.push(async () =>
-						handleInterbookResult(
-							await interbook.check_link(book_link),
+						emitLinkResult(
+							await checkLinkOnce(global_links_checked, link, () =>
+								interbook.check_link(book_link),
+							),
 							link,
 							htmlFile,
 							markdown_paths,
@@ -668,20 +710,19 @@
 				const url = links[i];
 				const isInternal = url.toLowerCase().includes("internal.hornbill.com");
 
-				externalChecks.push(async () => {
+				// Returns a page-independent { level, message } (or null for "say
+				// nothing") so the outcome can be cached per URL and replayed
+				// against every page that links to it.
+				const checkExternalUrl = async () => {
 					// For internal.hornbill.com links, check network reachability first (result cached)
 					if (isInternal) {
 						const on_int_net = await ensureIntNetCached();
 						if (!on_int_net) {
-							messages[htmlFile.relativePath].push(
-								`Outside of Hornbill network - skipping internal link validation for: ${url}`,
-							);
-							fs.appendFileSync(skip_link_file, `${url}\n`);
-							return;
+							return {
+								level: "skip",
+								message: `Outside of Hornbill network - skipping internal link validation for: ${url}`,
+							};
 						}
-						messages[htmlFile.relativePath].push(
-							`Inside of Hornbill network - performing internal link validation for: ${url}`,
-						);
 					}
 
 					try {
@@ -689,25 +730,39 @@
 						if ((status < 200 || status > 299) && status !== 304) {
 							if (process.env.GITHUB_ACTIONS === 'true' && status === 403 && url.includes(".hornbill.com")) {
 								// Always returns 403 for Hornbill sites through GitHub Actions — not a real error
-							} else {
-								throw `Unexpected Status Returned: ${status}`;
+								return null;
 							}
-						} else {
-							fs.appendFileSync(skip_link_file, `${url}\n`);
+							throw `Unexpected Status Returned: ${status}`;
 						}
+						return {
+							level: "ok",
+							message: `External link is valid: ${url}`,
+						};
 					} catch (e) {
 						let error_message;
 						if (e instanceof AggregateError) {
-							error_message = processErrorMessage(`Issue with external link [${url}]: ${e.message} - ${JSON.stringify(e.errors)}`, markdown_paths.relativePath, markdown_content, url);
+							error_message = `Issue with external link [${url}]: ${e.message} - ${JSON.stringify(e.errors)}`;
 						} else {
-							error_message = processErrorMessage(`Issue with external link [${url}]: ${e}`, markdown_paths.relativePath, markdown_content, url);
+							error_message = `Issue with external link [${url}]: ${e}`;
 						}
-						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);
+						const level =
+							hdocbook_project.validation.external_link_warnings ||
+							process.env.GITHUB_ACTIONS === 'true'
+								? "warning"
+								: "error";
+						return { level, message: error_message };
 					}
-				});
+				};
+
+				externalChecks.push(async () =>
+					emitLinkResult(
+						await checkLinkOnce(global_links_checked, url, checkExternalUrl),
+						url,
+						htmlFile,
+						markdown_paths,
+						markdown_content,
+					),
+				);
 			}
 		}
 
@@ -1136,7 +1191,9 @@
 		}
 
 		
-		const global_links_checked = [];
+		// link -> Promise<{ level, message } | null> for network checks: fetched
+		// once per run, but reported on every page that carries the link.
+		const global_links_checked = new Map();
 
 		for (const key in html_to_validate) {
 			const file = html_to_validate[key];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.62.3",
+	"version": "0.62.5",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {

package/templates/pdf/css/hdocs-pdf.css

@@ -462,6 +462,23 @@ code {
   font-size: 0.9em;
 }
 
+/* A PDF page cannot be scrolled, so a code block that overflows its box is
+   simply clipped at the page edge and the rest of the line is lost. Wrap
+   instead: pre-wrap keeps the authored newlines/indentation while allowing
+   long lines (curl one-liners, long endpoint URLs) to break. anywhere is
+   needed because break-word will not split an unbroken token such as a URL
+   or a base64 blob. .hljs is included because the highlight.js theme sets
+   overflow-x: auto on it, which is meaningless in print. */
+pre,
+pre code,
+.hljs {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  word-break: normal;
+  overflow-x: visible;
+  max-width: 100%;
+}
+
 /* From Bootstrap 5, text color decorations */
 .text-primary {
   color: #0d6efd !important;

package/templates/pdf/template.html

@@ -6,6 +6,12 @@
     <link rel="stylesheet"
         href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/base16/humanoid-light.min.css">
     <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
+    <!-- highlight.min.js is the "common" bundle only (~37 languages) and does NOT
+         include PowerShell, so language-powershell blocks rendered as plain black
+         text in PDFs while go/js/php/python/sh (all common) were coloured.
+         Register the extra grammar explicitly - keep the version in lockstep with
+         the core bundle above. -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/languages/powershell.min.js"></script>
 </head>
 
 <body>

package/ui/css/theme-default/styles/components/content.css

@@ -13,9 +13,15 @@
   position:relative;
 }
 
+/* The container is a flex row holding the content pane and the TOC. The
+   content pane does all the flexing (basis 0, min-width 0 so wide content -
+   tables, code blocks - cannot force it wider); the TOC keeps a fixed,
+   non-shrinking basis. Giving both children a width made the row
+   over-committed, so both shrank pro-rata and the TOC collapsed to ~118px. */
 .DocContent .injected-document-content
 {
-  width: 100%;
+  flex: 1 1 0;
+  min-width: 0;
 }
 
 .DocContent .injected-document-toc
@@ -23,7 +29,7 @@
   height: fit-content;
   display:none;
   margin:0 0 0 50px;
-  width:400px;
+  flex: 0 0 clamp(260px, 26%, 400px);
 }
 
 .DocContent .injected-document-toc .H2{
@@ -87,12 +93,9 @@
     display:inline-block;
   }
 
-  /* if have toc layout and greater than  1500px then limit doc content to 900px to make room for toc */
-  .DocContent.article-toc .injected-document-content
-  {
-      width: 900px;
-  }
-    
+  /* Room for the TOC comes from its own flex basis now - a width here would be
+     ignored anyway (flex-basis 0 on the content pane wins over width). */
+
 }
 
 /* style overrides to apply on screens that are 1920px and wider */

package/ui/js/highlightjs-badge.js

@@ -93,6 +93,33 @@ Uses some ES6 features so won't work in IE without shims:
 if (typeof highlightJsBadgeAutoLoad !== 'boolean')
     var highlightJsBadgeAutoLoad = false;
 
+//-- LOCAL FIX: display names for the badge label, so a fence written as ```md shows "Markdown".
+//-- highlight.js 11 grammars carry a cased `name` and are preferred when present, but the pack
+//-- vendored here is a v9 build whose grammars have aliases and no name at all - hence this
+//-- table. Keyed by alias as well as canonical name, because the badge label is whatever the
+//-- author typed in the fence. Anything missing falls through and displays unchanged.
+var HDOC_LANG_DISPLAY_NAMES = {
+    apache: "Apache", apacheconf: "Apache",
+    bash: "Bash", sh: "Bash", zsh: "Bash", shell: "Shell", console: "Shell Session",
+    bat: "DOS Batch", cmd: "DOS Batch", dos: "DOS Batch",
+    c: "C", cpp: "C++", cs: "C#", csharp: "C#", objectivec: "Objective-C",
+    css: "CSS", scss: "SCSS", less: "Less",
+    dart: "Dart", diff: "Diff", patch: "Diff", dns: "DNS Zone",
+    dockerfile: "Dockerfile", docker: "Dockerfile",
+    fsharp: "F#", go: "Go", golang: "Go", graphql: "GraphQL",
+    html: "HTML", xml: "XML", svg: "SVG", http: "HTTP",
+    ini: "INI", toml: "TOML", java: "Java",
+    js: "JavaScript", javascript: "JavaScript", json: "JSON",
+    kotlin: "Kotlin", lua: "Lua", makefile: "Makefile", md: "Markdown", markdown: "Markdown",
+    nginx: "Nginx", perl: "Perl", php: "PHP",
+    powershell: "PowerShell", ps: "PowerShell", ps1: "PowerShell", pwsh: "PowerShell",
+    python: "Python", py: "Python", r: "R", ruby: "Ruby", rb: "Ruby", rust: "Rust",
+    scala: "Scala", sql: "SQL", pgsql: "PostgreSQL", postgresql: "PostgreSQL",
+    swift: "Swift", ts: "TypeScript", typescript: "TypeScript",
+    vbnet: "VB.NET", vbscript: "VBScript", yaml: "YAML", yml: "YAML",
+    plaintext: "Plain Text", text: "Text"
+};
+
 function highlightJsBadge(opt) {
     var options = {
         // the selector for the badge template
@@ -198,10 +225,24 @@ function highlightJsBadge(opt) {
                 lang = "typescript";
             else if (lang == "fox")
                 lang = "foxpro";
-            else if (lang == "txt")                
+            else if (lang == "txt")
                 lang = "text"
 
-                
+            //-- LOCAL FIX: show a full display name rather than whatever alias the author wrote
+            //-- in the fence - "Markdown" not "md", "C#" not "cs", "Bash" not "sh". A
+            //-- highlight.js 11 grammar carries its own cased `name` and is authoritative, so
+            //-- this keeps working if the pack is ever upgraded; the v9 pack vendored here has
+            //-- no such property, so the table above supplies it. Unknown languages fall through
+            //-- to the overrides above unchanged.
+            var langDef = (window.hljs && typeof window.hljs.getLanguage === "function")
+                ? window.hljs.getLanguage(lang)
+                : null;
+
+            if (langDef && langDef.name)
+                lang = langDef.name;
+            else if (HDOC_LANG_DISPLAY_NAMES[lang])
+                lang = HDOC_LANG_DISPLAY_NAMES[lang];
+
             var html = hudText.replace("{{language}}", lang)
                               .replace("{{copyIconClass}}",options.copyIconClass)
                               .trim();
@@ -305,28 +346,22 @@ function highlightJsBadge(opt) {
             "    .code-badge-pre {",
             "        position: relative;",
             "    }",
+            "    /* Rendered as a full-width header bar above the code, not",
+            "       absolutely positioned over it - overlapping the first line",
+            "       made both the badge and the code unreadable. */",
             "    .code-badge {",
             "        display: flex;",
             "        flex-direction: row;",
+            "        align-items: center;",
+            "        justify-content: space-between;",
             "        white-space: normal;",
-            "        background: transparent;",
             "        background: #333;",
             "        color: white;",
             "        font-size: 0.875em;",
-            "        opacity: 0.5;",
-            "        transition: opacity linear 0.5s;",
-            "        border-radius: 0 0 0 7px;",
+            "        border-radius: 7px 7px 0 0;",
             "        padding: 5px 8px 5px 8px;",
-            "        position: absolute;",
-            "        right: 0;",
-            "        top: 0;",
-            "    }",            
-            "    .code-badge.active {",
-            "        opacity: 0.8;",
-            "    }",
-            "",
-            "    .code-badge:hover {",
-            "        opacity: .95;",
+            "        width: 100%;",
+            "        box-sizing: border-box;",
             "    }",
             "",
             "    .code-badge a,",
@@ -396,23 +431,16 @@ if (highlightJsBadgeAutoLoad)
     .code-badge {
         display: flex;
         flex-direction: row;
+        align-items: center;
+        justify-content: space-between;
         white-space: normal;
-        background: transparent;
         background: #333;
         color: white;
         font-size: 0.875em;
-        opacity: 0.5;
-        border-radius: 0 0 0 7px;
+        border-radius: 7px 7px 0 0;
         padding: 5px 8px 5px 8px;
-        position: absolute;
-        right: 0;
-        top: 0;
-    }
-    .code-badge.active {
-        opacity: 0.8;
-    }
-    .code-badge:hover {
-        opacity: .95;
+        width: 100%;
+        box-sizing: border-box;
     }
     .code-badge a,
     .code-badge a:hover {