kitfly 0.2.0 → 0.2.3

package/scripts/build.ts

@@ -5,6 +5,7 @@
  *
  * Options:
  *   -o, --out <dir>   Output directory [env: KITFLY_BUILD_OUT] [default: dist]
+ *   --profile <name>  Active content profile [env: KITFLY_PROFILE]
  *   --raw             Include raw markdown files [env: KITFLY_BUILD_RAW] [default: true]
  *   --no-raw          Don't include raw markdown files
  *   --help            Show help message
@@ -20,9 +21,10 @@ import { loadPluginInjections, type PluginInjections } from "../src/plugin-loade
 import {
 	buildBreadcrumbsStatic,
 	buildFooter,
+	buildLogoImgHtml,
 	buildNavStatic,
 	buildPageMeta,
-	buildSlideNav,
+	buildSlideNavHierarchical,
 	buildToc,
 	type ContentFile,
 	collectFiles,
@@ -35,17 +37,24 @@ import {
 	escapeHtml,
 	// File utilities
 	exists,
+	filterByProfile,
+	filterUnknownSlidesVisualsTypeDiagnostics,
 	// Provenance
 	generateProvenance,
+	loadDataBindings,
 	// YAML/Config parsing
 	loadSiteConfig,
+	mergeFrontmatterWithBody,
 	type Provenance,
+	pagePathForData,
 	// Markdown utilities
 	parseFrontmatter,
 	parseYaml,
+	resolveBindings,
 	resolveStylesPath,
 	resolveTemplatePath,
 	rewriteRelativeAssetUrls,
+	runPrebuildHooks,
 	// Types
 	type SiteConfig,
 	slugify,
@@ -59,6 +68,41 @@ const DEFAULT_OUT = "dist";
 
 let ROOT = process.cwd();
 let OUT_DIR = DEFAULT_OUT;
+let ACTIVE_PROFILE: string | undefined;
+
+async function applyDataBindingsToMarkdown(
+	rawMarkdown: string,
+	filePath: string,
+	config: SiteConfig,
+): Promise<{ frontmatter: Record<string, unknown>; body: string }> {
+	const parsed = parseFrontmatter(rawMarkdown);
+	const dataRef = typeof parsed.frontmatter.data === "string" ? parsed.frontmatter.data.trim() : "";
+	if (!dataRef) return parsed;
+
+	const pagePath = pagePathForData(ROOT, config.docroot, filePath);
+	const bindings = await loadDataBindings(dataRef, pagePath, ROOT, config.docroot, config.dataroot);
+	return {
+		frontmatter: parsed.frontmatter,
+		body: resolveBindings(parsed.body, bindings, pagePath),
+	};
+}
+
+async function applyDataBindingsForSlides(
+	rawMarkdown: string,
+	filePath: string,
+	config: SiteConfig,
+): Promise<string> {
+	const resolved = await applyDataBindingsToMarkdown(rawMarkdown, filePath, config);
+	return mergeFrontmatterWithBody(rawMarkdown, resolved.body);
+}
+
+function normalizeMsysPath(p: string): string {
+	// Git Bash / MSYS-style paths: /c/Users/... -> C:\Users\...
+	if (process.platform !== "win32") return p;
+	const m = p.match(/^\/([a-zA-Z])\/(.*)$/);
+	if (!m) return p;
+	return `${m[1].toUpperCase()}:\\${m[2].replaceAll("/", "\\")}`;
+}
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -68,6 +112,7 @@ interface ParsedArgs {
 	folder?: string;
 	out?: string;
 	raw?: boolean;
+	profile?: string;
 }
 
 function parseArgs(argv: string[]): ParsedArgs {
@@ -79,6 +124,9 @@ function parseArgs(argv: string[]): ParsedArgs {
 		if ((arg === "--out" || arg === "-o") && next && !next.startsWith("-")) {
 			result.out = next;
 			i++;
+		} else if (arg === "--profile" && next && !next.startsWith("-")) {
+			result.profile = next;
+			i++;
 		} else if (arg === "--raw") {
 			result.raw = true;
 		} else if (arg === "--no-raw") {
@@ -90,12 +138,13 @@ function parseArgs(argv: string[]): ParsedArgs {
 	return result;
 }
 
-function getConfig(): { folder?: string; out: string; raw: boolean } {
+function getConfig(): { folder?: string; out: string; raw: boolean; profile?: string } {
 	const args = parseArgs(process.argv.slice(2));
 	return {
 		folder: args.folder,
 		out: args.out ?? envString("KITFLY_BUILD_OUT", DEFAULT_OUT),
 		raw: args.raw ?? envBool("KITFLY_BUILD_RAW", true),
+		profile: args.profile ?? process.env.KITFLY_PROFILE,
 	};
 }
 
@@ -188,7 +237,7 @@ async function renderFile(
 		}
 		htmlContent = `<h1>${title}</h1>\n<pre><code class="language-json">${escapeHtml(prettyJson)}</code></pre>`;
 	} else {
-		const { frontmatter, body } = parseFrontmatter(content);
+		const { frontmatter, body } = await applyDataBindingsToMarkdown(content, filePath, config);
 		if (frontmatter.title) {
 			title = frontmatter.title as string;
 		}
@@ -198,7 +247,7 @@ async function renderFile(
 
 	const pathPrefix = computePathPrefix(urlKey);
 	const nav = buildNavStatic(files, urlKey, config, pathPrefix);
-	const footer = buildFooter(provenance, config);
+	const footer = buildFooter(provenance, config, pathPrefix);
 	const breadcrumbs = buildBreadcrumbsStatic(urlKey, pathPrefix, files, config);
 	const toc = buildToc(htmlContent);
 	const brandTarget = config.brand.external ? ' target="_blank" rel="noopener"' : "";
@@ -206,32 +255,50 @@ async function renderFile(
 	const prismUrls = getPrismUrls(theme);
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const mobileLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: `logo-img ${logoClass}`,
+		pathPrefix,
+		onerrorFallback: true,
+	});
+	const sidebarLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		pathPrefix,
+		onerrorFallback: true,
+	});
 
 	return template
 		.replace("{{BODY_CLASS}}", "mode-docs")
-		.replace(/\{\{PATH_PREFIX\}\}/g, pathPrefix)
-		.replace(/\{\{BRAND_URL\}\}/g, config.brand.url)
-		.replace(/\{\{BRAND_TARGET\}\}/g, brandTarget)
-		.replace(/\{\{BRAND_NAME\}\}/g, config.brand.name)
-		.replace(/\{\{BRAND_INITIAL\}\}/g, brandInitial)
-		.replace(/\{\{BRAND_LOGO\}\}/g, config.brand.logo || "assets/brand/logo.png")
-		.replace(/\{\{BRAND_FAVICON\}\}/g, config.brand.favicon || "assets/brand/favicon.png")
-		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, logoClass)
-		.replace(/\{\{SITE_TITLE\}\}/g, config.title)
-		.replace("{{TITLE}}", title)
-		.replace("{{VERSION}}", uiVersion)
-		.replace("{{BRANCH}}", provenance.gitBranch)
-		.replace("{{BREADCRUMBS}}", breadcrumbs)
-		.replace("{{PAGE_META}}", pageMeta)
-		.replace("{{NAV}}", nav)
-		.replace("{{CONTENT}}", htmlContent)
-		.replace("{{TOC}}", toc)
-		.replace("{{FOOTER}}", footer)
-		.replace("{{THEME_CSS}}", themeCSS)
-		.replace("{{PLUGIN_HEAD}}", plugins.head)
-		.replace("{{PLUGIN_BODY_END}}", plugins.bodyEnd)
-		.replace("{{PRISM_LIGHT_URL}}", prismUrls.light)
-		.replace("{{PRISM_DARK_URL}}", prismUrls.dark)
+		.replace(/\{\{PATH_PREFIX\}\}/g, () => pathPrefix)
+		.replace(/\{\{BRAND_URL\}\}/g, () => config.brand.url)
+		.replace(/\{\{BRAND_TARGET\}\}/g, () => brandTarget)
+		.replace(/\{\{BRAND_NAME\}\}/g, () => config.brand.name)
+		.replace(/\{\{BRAND_INITIAL\}\}/g, () => brandInitial)
+		.replace("{{MOBILE_BRAND_LOGO_IMG}}", () => mobileLogoHtml)
+		.replace("{{SIDEBAR_BRAND_LOGO_IMG}}", () => sidebarLogoHtml)
+		.replace(/\{\{BRAND_LOGO\}\}/g, () => config.brand.logo || "assets/brand/logo.png")
+		.replace(/\{\{BRAND_FAVICON\}\}/g, () => config.brand.favicon || "assets/brand/favicon.png")
+		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, () => logoClass)
+		.replace(/\{\{SITE_TITLE\}\}/g, () => config.title)
+		.replace("{{TITLE}}", () => title)
+		.replace("{{VERSION}}", () => uiVersion)
+		.replace("{{BRANCH}}", () => provenance.gitBranch)
+		.replace("{{BREADCRUMBS}}", () => breadcrumbs)
+		.replace("{{PAGE_META}}", () => pageMeta)
+		.replace("{{NAV}}", () => nav)
+		.replace("{{CONTENT}}", () => htmlContent)
+		.replace("{{TOC}}", () => toc)
+		.replace("{{FOOTER}}", () => footer)
+		.replace("{{THEME_CSS}}", () => themeCSS)
+		.replace("{{PLUGIN_HEAD}}", () => plugins.head)
+		.replace("{{PLUGIN_BODY_END}}", () => plugins.bodyEnd)
+		.replace("{{PRISM_LIGHT_URL}}", () => prismUrls.light)
+		.replace("{{PRISM_DARK_URL}}", () => prismUrls.dark)
 		.replace("{{HOT_RELOAD_SCRIPT}}", "");
 }
 
@@ -273,32 +340,50 @@ sections:
 	const pathPrefix = "./";
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const mobileLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: `logo-img ${logoClass}`,
+		pathPrefix,
+		onerrorFallback: true,
+	});
+	const sidebarLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		pathPrefix,
+		onerrorFallback: true,
+	});
 
 	return template
 		.replace("{{BODY_CLASS}}", "mode-docs")
-		.replace(/\{\{PATH_PREFIX\}\}/g, pathPrefix)
-		.replace(/\{\{BRAND_URL\}\}/g, config.brand.url)
-		.replace(/\{\{BRAND_TARGET\}\}/g, brandTarget)
-		.replace(/\{\{BRAND_NAME\}\}/g, config.brand.name)
-		.replace(/\{\{BRAND_INITIAL\}\}/g, brandInitial)
-		.replace(/\{\{BRAND_LOGO\}\}/g, config.brand.logo || "assets/brand/logo.png")
-		.replace(/\{\{BRAND_FAVICON\}\}/g, config.brand.favicon || "assets/brand/favicon.png")
-		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, logoClass)
-		.replace(/\{\{SITE_TITLE\}\}/g, config.title)
+		.replace(/\{\{PATH_PREFIX\}\}/g, () => pathPrefix)
+		.replace(/\{\{BRAND_URL\}\}/g, () => config.brand.url)
+		.replace(/\{\{BRAND_TARGET\}\}/g, () => brandTarget)
+		.replace(/\{\{BRAND_NAME\}\}/g, () => config.brand.name)
+		.replace(/\{\{BRAND_INITIAL\}\}/g, () => brandInitial)
+		.replace("{{MOBILE_BRAND_LOGO_IMG}}", () => mobileLogoHtml)
+		.replace("{{SIDEBAR_BRAND_LOGO_IMG}}", () => sidebarLogoHtml)
+		.replace(/\{\{BRAND_LOGO\}\}/g, () => config.brand.logo || "assets/brand/logo.png")
+		.replace(/\{\{BRAND_FAVICON\}\}/g, () => config.brand.favicon || "assets/brand/favicon.png")
+		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, () => logoClass)
+		.replace(/\{\{SITE_TITLE\}\}/g, () => config.title)
 		.replace("{{TITLE}}", "Getting Started")
-		.replace("{{VERSION}}", uiVersion)
-		.replace("{{BRANCH}}", provenance.gitBranch)
+		.replace("{{VERSION}}", () => uiVersion)
+		.replace("{{BRANCH}}", () => provenance.gitBranch)
 		.replace("{{BREADCRUMBS}}", "")
 		.replace("{{PAGE_META}}", "")
 		.replace("{{NAV}}", "<ul></ul>")
-		.replace("{{CONTENT}}", htmlContent)
+		.replace("{{CONTENT}}", () => htmlContent)
 		.replace("{{TOC}}", "")
-		.replace("{{FOOTER}}", buildFooter(provenance, config))
-		.replace("{{THEME_CSS}}", themeCSS)
-		.replace("{{PLUGIN_HEAD}}", plugins.head)
-		.replace("{{PLUGIN_BODY_END}}", plugins.bodyEnd)
-		.replace("{{PRISM_LIGHT_URL}}", prismUrls.light)
-		.replace("{{PRISM_DARK_URL}}", prismUrls.dark)
+		.replace("{{FOOTER}}", () => buildFooter(provenance, config, pathPrefix))
+		.replace("{{THEME_CSS}}", () => themeCSS)
+		.replace("{{PLUGIN_HEAD}}", () => plugins.head)
+		.replace("{{PLUGIN_BODY_END}}", () => plugins.bodyEnd)
+		.replace("{{PRISM_LIGHT_URL}}", () => prismUrls.light)
+		.replace("{{PRISM_DARK_URL}}", () => prismUrls.dark)
 		.replace("{{HOT_RELOAD_SCRIPT}}", "");
 }
 
@@ -312,7 +397,9 @@ async function renderSlidesIndex(
 ): Promise<string> {
 	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
 	const pathPrefix = "./";
-	const slides = await collectSlides(files);
+	const slides = await collectSlides(files, {
+		markdownTransform: (raw, file) => applyDataBindingsForSlides(raw, file.path, config),
+	});
 	let validateFences = false;
 	try {
 		const raw = await readFile(join(ROOT, "kitfly.plugins.yaml"), "utf-8");
@@ -327,7 +414,9 @@ async function renderSlidesIndex(
 			let inner = "";
 			if (slide.kind === "markdown") {
 				if (validateFences) {
-					const diagnostics = validateSlidesVisualsFences(slide.body);
+					const diagnostics = filterUnknownSlidesVisualsTypeDiagnostics(
+						validateSlidesVisualsFences(slide.body),
+					);
 					if (diagnostics.length) {
 						const msg = diagnostics
 							.slice(0, 12)
@@ -373,38 +462,56 @@ async function renderSlidesIndex(
           </div>
         </div>`;
 
-	const nav = buildSlideNav(slides, config, "slide-1");
+	const nav = buildSlideNavHierarchical(slides, config, "slide-1");
 	const brandTarget = config.brand.external ? ' target="_blank" rel="noopener"' : "";
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
 	const themeCSS = generateThemeCSS(theme);
 	const prismUrls = getPrismUrls(theme);
 	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
+	const mobileLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: `logo-img ${logoClass}`,
+		pathPrefix,
+		onerrorFallback: true,
+	});
+	const sidebarLogoHtml = buildLogoImgHtml({
+		logo: config.brand.logo || "assets/brand/logo.png",
+		logoDark: config.brand.logoDark,
+		alt: config.brand.name,
+		className: "logo-img",
+		pathPrefix,
+		onerrorFallback: true,
+	});
 
 	return template
 		.replace("{{BODY_CLASS}}", "mode-slides")
-		.replace(/\{\{PATH_PREFIX\}\}/g, pathPrefix)
-		.replace(/\{\{BRAND_URL\}\}/g, config.brand.url)
-		.replace(/\{\{BRAND_TARGET\}\}/g, brandTarget)
-		.replace(/\{\{BRAND_NAME\}\}/g, config.brand.name)
-		.replace(/\{\{BRAND_INITIAL\}\}/g, brandInitial)
-		.replace(/\{\{BRAND_LOGO\}\}/g, config.brand.logo || "assets/brand/logo.png")
-		.replace(/\{\{BRAND_FAVICON\}\}/g, config.brand.favicon || "assets/brand/favicon.png")
-		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, logoClass)
-		.replace(/\{\{SITE_TITLE\}\}/g, config.title)
-		.replace("{{TITLE}}", config.title)
-		.replace("{{VERSION}}", uiVersion)
-		.replace("{{BRANCH}}", provenance.gitBranch)
+		.replace(/\{\{PATH_PREFIX\}\}/g, () => pathPrefix)
+		.replace(/\{\{BRAND_URL\}\}/g, () => config.brand.url)
+		.replace(/\{\{BRAND_TARGET\}\}/g, () => brandTarget)
+		.replace(/\{\{BRAND_NAME\}\}/g, () => config.brand.name)
+		.replace(/\{\{BRAND_INITIAL\}\}/g, () => brandInitial)
+		.replace("{{MOBILE_BRAND_LOGO_IMG}}", () => mobileLogoHtml)
+		.replace("{{SIDEBAR_BRAND_LOGO_IMG}}", () => sidebarLogoHtml)
+		.replace(/\{\{BRAND_LOGO\}\}/g, () => config.brand.logo || "assets/brand/logo.png")
+		.replace(/\{\{BRAND_FAVICON\}\}/g, () => config.brand.favicon || "assets/brand/favicon.png")
+		.replace(/\{\{BRAND_LOGO_CLASS\}\}/g, () => logoClass)
+		.replace(/\{\{SITE_TITLE\}\}/g, () => config.title)
+		.replace("{{TITLE}}", () => config.title)
+		.replace("{{VERSION}}", () => uiVersion)
+		.replace("{{BRANCH}}", () => provenance.gitBranch)
 		.replace("{{BREADCRUMBS}}", "")
 		.replace("{{PAGE_META}}", "")
-		.replace("{{NAV}}", nav)
-		.replace("{{CONTENT}}", htmlContent)
+		.replace("{{NAV}}", () => nav)
+		.replace("{{CONTENT}}", () => htmlContent)
 		.replace("{{TOC}}", "")
-		.replace("{{FOOTER}}", buildFooter(provenance, config))
-		.replace("{{THEME_CSS}}", themeCSS)
-		.replace("{{PLUGIN_HEAD}}", plugins.head)
-		.replace("{{PLUGIN_BODY_END}}", plugins.bodyEnd)
-		.replace("{{PRISM_LIGHT_URL}}", prismUrls.light)
-		.replace("{{PRISM_DARK_URL}}", prismUrls.dark)
+		.replace("{{FOOTER}}", () => buildFooter(provenance, config, pathPrefix))
+		.replace("{{THEME_CSS}}", () => themeCSS)
+		.replace("{{PLUGIN_HEAD}}", () => plugins.head)
+		.replace("{{PLUGIN_BODY_END}}", () => plugins.bodyEnd)
+		.replace("{{PRISM_LIGHT_URL}}", () => prismUrls.light)
+		.replace("{{PRISM_DARK_URL}}", () => prismUrls.dark)
 		.replace("{{HOT_RELOAD_SCRIPT}}", "");
 }
 
@@ -413,6 +520,7 @@ export interface BuildOptions {
 	folder?: string;
 	out?: string;
 	raw?: boolean; // Include raw markdown files (default: true)
+	profile?: string;
 }
 
 let INCLUDE_RAW = true;
@@ -427,18 +535,29 @@ export async function build(options: BuildOptions = {}) {
 	if (options.raw === false) {
 		INCLUDE_RAW = false;
 	}
+	ACTIVE_PROFILE = options.profile;
 	await buildSite();
 }
 
 // Rename internal function
 async function buildSite() {
-	const DIST = join(ROOT, OUT_DIR);
+	const DIST = resolve(ROOT, normalizeMsysPath(OUT_DIR));
 
 	console.log("Building site...\n");
 
 	// Load configuration
 	const config = await loadSiteConfig(ROOT);
 	console.log(`  ✓ Loaded config: "${config.title}" (${config.sections.length} sections)`);
+	if (config.prebuild?.length) {
+		await runPrebuildHooks(
+			config.prebuild,
+			ROOT,
+			"build",
+			ACTIVE_PROFILE,
+			config.dataroot || "data",
+		);
+		console.log(`  ✓ prebuild hooks (${config.prebuild.length})`);
+	}
 
 	// Load theme
 	const theme = await loadTheme(ROOT);
@@ -496,7 +615,11 @@ async function buildSite() {
 	}
 
 	// Collect and render all files
-	const files = await collectFiles(ROOT, config);
+	const files = await filterByProfile(
+		await collectFiles(ROOT, config),
+		ACTIVE_PROFILE,
+		config.profiles,
+	);
 
 	if (files.length === 0) {
 		// No content - render Getting Started page
@@ -730,6 +853,7 @@ Usage: bun run build [folder] [options]
 
 Options:
   -o, --out <dir>       Output directory [env: KITFLY_BUILD_OUT] [default: ${DEFAULT_OUT}]
+  --profile <name>      Active content profile [env: KITFLY_PROFILE]
   --raw                 Include raw markdown files [env: KITFLY_BUILD_RAW] [default: true]
   --no-raw              Don't include raw markdown files
   --help                Show this help message
@@ -749,5 +873,6 @@ Examples:
 		folder: cfg.folder,
 		out: cfg.out,
 		raw: cfg.raw,
+		profile: cfg.profile,
 	}).catch(console.error);
 }