hdoc-tools 0.65.0 → 0.66.0

package/hdoc-serve-validate.js

@@ -329,10 +329,20 @@ exports.validate_page = async (args) => {
 	const warnings = [];
 	const skipped = [];
 
-	// 1) filename convention (mirrors hdoc-build.js; _-prefixed and *_ext.md
-	// files never reach here — resolve_page_md refuses them)
+	// _inline pages get the build pipeline's relaxed rules: no filename
+	// convention, fully-qualified Hornbill Docs links allowed, and links
+	// need not be root-relative.
+	const is_inline = rel.includes("/_inline/");
+
+	// 1) filename convention (mirrors hdoc-build.js; _inline and *_ext.md
+	// files are exempt, as in the full build)
 	const stem = path.basename(rel).replace(/\.md$/i, "");
-	if (!DOC_FILENAME_RE.test(stem) && stem !== "index") {
+	if (
+		!is_inline &&
+		!stem.endsWith("_ext") &&
+		!DOC_FILENAME_RE.test(stem) &&
+		stem !== "index"
+	) {
 		errors.push(
 			`Filename does not meet naming standards (^[a-z]+[-a-z0-9]+$): ${path.basename(rel)}`,
 		);
@@ -422,6 +432,18 @@ exports.validate_page = async (args) => {
 				lower.includes("docs.hornbill.com") ||
 				lower.includes("docs-internal.hornbill.com")
 			) {
+				// _inline content is embedded in the app, so fully-qualified
+				// docs links are permitted there (build behavior); whether a
+				// docs-internal link is allowed depends on the repo being
+				// private, which only the full validate knows
+				if (is_inline) {
+					skipped.push(
+						lower.includes("docs-internal.hornbill.com")
+							? `docs-internal link not checked (public-repo rule runs in full validate): ${href}`
+							: `Hornbill Docs link not checked (run a full validate): ${href}`,
+					);
+					return;
+				}
 				errors.push(
 					`Hornbill Docs links should not be fully-qualified: ${href}`,
 				);
@@ -433,6 +455,12 @@ exports.validate_page = async (args) => {
 		}
 
 		if (!href.startsWith("/")) {
+			// the root-relative rule does not apply inside _inline (build
+			// behavior); the target cannot be resolved the same way, so skip
+			if (is_inline) {
+				skipped.push(`Relative link not checked (inline content): ${href}`);
+				return;
+			}
 			errors.push(
 				`Root relative links should start with a forward-slash: ${href}`,
 			);

package/hdoc-toc.js

@@ -263,8 +263,13 @@ class TocModel {
 		if (segs.includes("..") || segs.includes(".")) {
 			throw new Error("Invalid path");
 		}
-		if (segs.some((s) => s.startsWith("_"))) {
-			throw new Error("Cannot operate inside special (_) folders");
+		// Special "_" folders are off-limits, with one exception: _inline
+		// directly under the book root holds real, editable inline-help pages
+		// (they render in serve/build and are exempt from the nav tree).
+		for (let i = 0; i < segs.length; i++) {
+			if (segs[i].startsWith("_") && !(i === 1 && segs[i] === "_inline")) {
+				throw new Error("Cannot operate inside special (_) folders");
+			}
 		}
 		if (!dir && exts) {
 			const lower = norm.toLowerCase();
@@ -293,32 +298,43 @@ class TocModel {
 		return set;
 	}
 
-	// Every file on disk under the book (excluding "_" folders), each tagged with
+	// Every file on disk under the book (excluding "_" folders, except _inline
+	// at the book root — those are real inline-help pages), each tagged with
 	// its kind (page/image/other). Pages also carry a linked flag (in nav or not).
 	list_files() {
 		const linked = this.linked_files();
 		const root = path.join(this.source_path, this.docId);
 		const files = [];
 		const dirs = [];
-		const walk = (absDir) => {
+		const walk = (absDir, in_inline) => {
 			for (const e of fs.readdirSync(absDir, { withFileTypes: true })) {
-				if (e.name.startsWith("_")) continue; // skip special folders/files
+				if (e.name.startsWith("_")) {
+					// _inline at the book root is editable content; every other
+					// _ entry stays hidden (and blocked by _safe_rel)
+					if (!(absDir === root && e.name === "_inline" && e.isDirectory()))
+						continue;
+				}
 				const abs = path.join(absDir, e.name);
 				const rel = path.relative(this.source_path, abs).split(path.sep).join("/");
+				const inline = in_inline || e.name === "_inline";
 				if (e.isDirectory()) {
 					dirs.push(rel);
-					walk(abs);
+					walk(abs, inline);
 				} else {
 					const kind = kind_of(e.name);
 					files.push({
 						file: rel,
 						kind,
-						linked: kind === "page" ? linked.has(rel) : false,
+						// _inline pages are referenced from app help contexts, never
+						// the contents tree — report them linked so the unlinked
+						// badge/filter stays meaningful
+						linked:
+							kind === "page" ? (inline ? true : linked.has(rel)) : false,
 					});
 				}
 			}
 		};
-		if (fs.existsSync(root)) walk(root);
+		if (fs.existsSync(root)) walk(root, false);
 		files.sort((a, b) => a.file.localeCompare(b.file));
 		dirs.sort((a, b) => a.localeCompare(b));
 		return { docId: this.docId, dirs, files };

package/package.json

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