kitfly 0.1.2 → 0.2.0

package/schemas/v0/site.schema.json

@@ -5,7 +5,11 @@
   "title": "Site Configuration",
   "description": "Configuration for Kitfly static site generator",
   "type": "object",
-  "required": ["title", "brand", "sections"],
+  "required": [
+    "title",
+    "brand",
+    "sections"
+  ],
   "properties": {
     "schemaVersion": {
       "type": "string",
@@ -25,8 +29,35 @@
     },
     "version": {
       "type": "string",
-      "description": "Site version displayed in footer provenance",
-      "examples": ["1.0.0", "2024.03", "draft"]
+      "description": "Site version shown in footer provenance. Supports literal values, auto (read VERSION in site root), or file:<path> (read from relative file).",
+      "examples": [
+        "1.0.0",
+        "2024.03",
+        "draft",
+        "auto",
+        "file:VERSION",
+        "file:./meta/site version.txt"
+      ]
+    },
+    "mode": {
+      "type": "string",
+      "description": "Site layout mode",
+      "enum": [
+        "docs",
+        "slides"
+      ],
+      "default": "docs"
+    },
+    "aspect": {
+      "type": "string",
+      "description": "Slide aspect ratio (only applies when mode is slides)",
+      "enum": [
+        "16/9",
+        "4/3",
+        "3/2",
+        "16/10"
+      ],
+      "default": "16/9"
     },
     "home": {
       "type": "string",
@@ -35,7 +66,10 @@
     "brand": {
       "type": "object",
       "description": "Brand configuration for logo and links",
-      "required": ["name", "url"],
+      "required": [
+        "name",
+        "url"
+      ],
       "properties": {
         "name": {
           "type": "string",
@@ -64,7 +98,10 @@
         "logoType": {
           "type": "string",
           "description": "Logo type: icon (square) or wordmark (wide)",
-          "enum": ["icon", "wordmark"],
+          "enum": [
+            "icon",
+            "wordmark"
+          ],
           "default": "icon"
         }
       },
@@ -76,7 +113,10 @@
       "minItems": 1,
       "items": {
         "type": "object",
-        "required": ["name", "path"],
+        "required": [
+          "name",
+          "path"
+        ],
         "properties": {
           "name": {
             "type": "string",
@@ -90,7 +130,9 @@
           "files": {
             "type": "array",
             "description": "Specific files to include (for root-level sections)",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            }
           },
           "maxDepth": {
             "type": "integer",
@@ -102,7 +144,9 @@
           "exclude": {
             "type": "array",
             "description": "Glob patterns to exclude from auto-discovery",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string"
+            }
           }
         },
         "additionalProperties": false
@@ -126,7 +170,10 @@
           "maxItems": 10,
           "items": {
             "type": "object",
-            "required": ["text", "url"],
+            "required": [
+              "text",
+              "url"
+            ],
             "properties": {
               "text": {
                 "type": "string",

package/schemas/v0/theme.schema.json

@@ -14,7 +14,11 @@
       "type": "string",
       "description": "Theme name for identification",
       "maxLength": 50,
-      "examples": ["Kitfly Default", "GitHub", "Paper"]
+      "examples": [
+        "Kitfly Default",
+        "GitHub",
+        "Paper"
+      ]
     },
     "layout": {
       "type": "object",
@@ -25,7 +29,11 @@
           "description": "Sidebar width (CSS length value)",
           "pattern": "^[0-9]+(px|rem|em|%)$",
           "default": "280px",
-          "examples": ["280px", "320px", "18rem"]
+          "examples": [
+            "280px",
+            "320px",
+            "18rem"
+          ]
         }
       },
       "additionalProperties": false
@@ -33,10 +41,17 @@
     "colors": {
       "type": "object",
       "description": "Color palettes for light and dark modes",
-      "required": ["light", "dark"],
+      "required": [
+        "light",
+        "dark"
+      ],
       "properties": {
-        "light": { "$ref": "#/$defs/colorPalette" },
-        "dark": { "$ref": "#/$defs/colorPalette" }
+        "light": {
+          "$ref": "#/$defs/colorPalette"
+        },
+        "dark": {
+          "$ref": "#/$defs/colorPalette"
+        }
       },
       "additionalProperties": false
     },
@@ -47,13 +62,25 @@
         "light": {
           "type": "string",
           "description": "Prism theme for light mode",
-          "enum": ["default", "coy", "solarized-light", "tomorrow"],
+          "enum": [
+            "default",
+            "coy",
+            "solarized-light",
+            "tomorrow"
+          ],
           "default": "default"
         },
         "dark": {
           "type": "string",
           "description": "Prism theme for dark mode",
-          "enum": ["okaidia", "tomorrow-night", "nord", "dracula", "one-dark", "synthwave84"],
+          "enum": [
+            "okaidia",
+            "tomorrow-night",
+            "nord",
+            "dracula",
+            "one-dark",
+            "synthwave84"
+          ],
           "default": "okaidia"
         }
       },
@@ -66,19 +93,31 @@
         "body": {
           "type": "string",
           "description": "Font preset for body text",
-          "enum": ["system", "mono", "serif", "readable"],
+          "enum": [
+            "system",
+            "mono",
+            "serif",
+            "readable"
+          ],
           "default": "system"
         },
         "headings": {
           "type": "string",
           "description": "Font preset for headings",
-          "enum": ["system", "mono", "serif", "readable"],
+          "enum": [
+            "system",
+            "mono",
+            "serif",
+            "readable"
+          ],
           "default": "system"
         },
         "code": {
           "type": "string",
           "description": "Font preset for code blocks",
-          "enum": ["mono"],
+          "enum": [
+            "mono"
+          ],
           "default": "mono"
         },
         "baseSize": {
@@ -86,12 +125,22 @@
           "description": "Base font size",
           "pattern": "^[0-9]+(px|rem|em)$",
           "default": "16px",
-          "examples": ["16px", "17px", "1rem"]
+          "examples": [
+            "16px",
+            "17px",
+            "1rem"
+          ]
         },
         "scale": {
           "type": "string",
           "description": "Type scale ratio for heading sizes",
-          "enum": ["1.125", "1.2", "1.25", "1.333", "1.5"],
+          "enum": [
+            "1.125",
+            "1.2",
+            "1.25",
+            "1.333",
+            "1.5"
+          ],
           "default": "1.25"
         }
       },
@@ -103,61 +152,95 @@
     "colorPalette": {
       "type": "object",
       "description": "Color palette for a single mode (light or dark)",
-      "required": ["background", "surface", "text", "heading", "primary", "border"],
+      "required": [
+        "background",
+        "surface",
+        "text",
+        "heading",
+        "primary",
+        "border"
+      ],
       "properties": {
         "background": {
           "type": "string",
           "description": "Page background color",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#ffffff", "#0f1e2b"]
+          "examples": [
+            "#ffffff",
+            "#0f1e2b"
+          ]
         },
         "surface": {
           "type": "string",
           "description": "Elevated surface color (cards, code blocks)",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#f5f7f8", "#152F46"]
+          "examples": [
+            "#f5f7f8",
+            "#152F46"
+          ]
         },
         "text": {
           "type": "string",
           "description": "Primary body text color",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#374151", "#e5e7eb"]
+          "examples": [
+            "#374151",
+            "#e5e7eb"
+          ]
         },
         "textMuted": {
           "type": "string",
           "description": "Secondary/muted text color",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#6b7280", "#9ca3af"]
+          "examples": [
+            "#6b7280",
+            "#9ca3af"
+          ]
         },
         "heading": {
           "type": "string",
           "description": "Heading text color",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#152F46", "#f9fafb"]
+          "examples": [
+            "#152F46",
+            "#f9fafb"
+          ]
         },
         "primary": {
           "type": "string",
           "description": "Primary accent color (links, buttons)",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#007182", "#4db8c7"]
+          "examples": [
+            "#007182",
+            "#4db8c7"
+          ]
         },
         "primaryHover": {
           "type": "string",
           "description": "Primary color hover state",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#005c6a", "#6cc9d6"]
+          "examples": [
+            "#005c6a",
+            "#6cc9d6"
+          ]
         },
         "accent": {
           "type": "string",
           "description": "Secondary accent color (highlights, CTAs)",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#D17059", "#e8947f"]
+          "examples": [
+            "#D17059",
+            "#e8947f"
+          ]
         },
         "border": {
           "type": "string",
           "description": "Border and divider color",
           "pattern": "^#[0-9a-fA-F]{6}$",
-          "examples": ["#e5e7eb", "#374151"]
+          "examples": [
+            "#e5e7eb",
+            "#374151"
+          ]
         }
       },
       "additionalProperties": false

package/scripts/build.ts

@@ -16,15 +16,18 @@ import { copyFile, cp, mkdir, readdir, readFile, stat, writeFile } from "node:fs
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { marked, Renderer } from "marked";
 import { ENGINE_ASSETS_DIR } from "../src/engine.ts";
+import { loadPluginInjections, type PluginInjections } from "../src/plugin-loader.ts";
 import {
 	buildBreadcrumbsStatic,
 	buildFooter,
 	buildNavStatic,
 	buildPageMeta,
+	buildSlideNav,
 	buildToc,
 	type ContentFile,
-	// Navigation/template building
 	collectFiles,
+	// Navigation/template building
+	collectSlides,
 	envBool,
 	// Config helpers
 	envString,
@@ -39,12 +42,15 @@ import {
 	type Provenance,
 	// Markdown utilities
 	parseFrontmatter,
+	parseYaml,
 	resolveStylesPath,
 	resolveTemplatePath,
+	rewriteRelativeAssetUrls,
 	// Types
 	type SiteConfig,
 	slugify,
 	validatePath,
+	validateSlidesVisualsFences,
 } from "../src/shared.ts";
 import { generateThemeCSS, getPrismUrls, loadTheme, type Theme } from "../src/theme.ts";
 
@@ -161,6 +167,7 @@ async function renderFile(
 	provenance: Provenance,
 	config: SiteConfig,
 	theme: Theme,
+	plugins: PluginInjections,
 ): Promise<string> {
 	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
 	const content = await readFile(filePath, "utf-8");
@@ -198,12 +205,15 @@ async function renderFile(
 	const themeCSS = generateThemeCSS(theme);
 	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");
 
 	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)
@@ -218,6 +228,8 @@ async function renderFile(
 		.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}}", "");
@@ -229,6 +241,7 @@ function renderGettingStarted(
 	provenance: Provenance,
 	config: SiteConfig,
 	theme: Theme,
+	plugins: PluginInjections,
 ): string {
 	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
 	const htmlContent = `
@@ -259,12 +272,15 @@ sections:
 	const prismUrls = getPrismUrls(theme);
 	const pathPrefix = "./";
 	const logoClass = config.brand.logoType === "wordmark" ? "logo-wordmark" : "logo-icon";
+	const brandInitial = escapeHtml(config.brand.name.trim().charAt(0).toUpperCase() || "K");
 
 	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)
@@ -279,6 +295,114 @@ sections:
 		.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("{{HOT_RELOAD_SCRIPT}}", "");
+}
+
+async function renderSlidesIndex(
+	template: string,
+	files: ContentFile[],
+	provenance: Provenance,
+	config: SiteConfig,
+	theme: Theme,
+	plugins: PluginInjections,
+): Promise<string> {
+	const uiVersion = provenance.version ? `v${provenance.version}` : "unversioned";
+	const pathPrefix = "./";
+	const slides = await collectSlides(files);
+	let validateFences = false;
+	try {
+		const raw = await readFile(join(ROOT, "kitfly.plugins.yaml"), "utf-8");
+		const parsed = parseYaml(raw) as unknown as Record<string, unknown>;
+		const enabled = Array.isArray(parsed?.plugins) ? (parsed.plugins as unknown[]) : [];
+		validateFences = enabled.some((p) => typeof p === "string" && p.startsWith("slides-visuals@"));
+	} catch {
+		// no config, skip
+	}
+	const renderedSlides = await Promise.all(
+		slides.map(async (slide, i) => {
+			let inner = "";
+			if (slide.kind === "markdown") {
+				if (validateFences) {
+					const diagnostics = validateSlidesVisualsFences(slide.body);
+					if (diagnostics.length) {
+						const msg = diagnostics
+							.slice(0, 12)
+							.map((d) => `  - ${slide.sourcePath}:${d.line} ${d.message}`)
+							.join("\n");
+						throw new Error(`slides-visuals fence contract violations:\n${msg}`);
+					}
+				}
+				inner = marked.parse(slide.body) as string;
+			} else if (slide.kind === "yaml") {
+				inner = `<pre><code class="language-yaml">${escapeHtml(slide.body)}</code></pre>`;
+			} else {
+				let prettyJson = slide.body;
+				try {
+					prettyJson = JSON.stringify(JSON.parse(slide.body), null, 2);
+				} catch {
+					// Use original if not valid JSON
+				}
+				inner = `<pre><code class="language-json">${escapeHtml(prettyJson)}</code></pre>`;
+			}
+			inner = rewriteRelativeAssetUrls(inner, slide.sourceUrlPath, pathPrefix);
+
+			const activeClass = i === 0 ? " active" : "";
+			const classToken = slide.className ? ` ${slide.className}` : "";
+			return `<section id="${slide.id}" class="slide${classToken}${activeClass}" data-slide-index="${i}">${inner}</section>`;
+		}),
+	);
+
+	const htmlContent = `
+        <div class="slides-shell" style="--slide-aspect: ${config.aspect || "16/9"}">
+          <div class="slide-viewport">
+            <div class="slide-frame">
+              ${renderedSlides.join("\n")}
+            </div>
+          </div>
+          <div class="slide-nav" aria-label="Slide navigation">
+            <button class="slide-prev" type="button" aria-label="Previous slide">Prev</button>
+            <span class="slide-counter">1 / ${slides.length}</span>
+            <button class="slide-next" type="button" aria-label="Next slide">Next</button>
+            <div class="slide-progress" role="presentation">
+              <span class="slide-progress-bar" style="width: ${(1 / slides.length) * 100}%"></span>
+            </div>
+          </div>
+        </div>`;
+
+	const nav = buildSlideNav(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");
+
+	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("{{BREADCRUMBS}}", "")
+		.replace("{{PAGE_META}}", "")
+		.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("{{HOT_RELOAD_SCRIPT}}", "");
@@ -333,6 +457,12 @@ async function buildSite() {
 	// Read template
 	const template = await readFile(await resolveTemplatePath(ROOT), "utf-8");
 
+	// Load plugin injections (optional; no-op when kitfly.plugins.yaml is absent)
+	const plugins = await loadPluginInjections({
+		root: ROOT,
+		mode: config.mode === "slides" ? "slides" : "docs",
+	});
+
 	// Copy CSS
 	const css = await readFile(await resolveStylesPath(ROOT), "utf-8");
 	await writeFile(join(DIST, "styles.css"), css);
@@ -370,13 +500,23 @@ async function buildSite() {
 
 	if (files.length === 0) {
 		// No content - render Getting Started page
-		const html = renderGettingStarted(template, provenance, config, theme);
+		const html = renderGettingStarted(template, provenance, config, theme, plugins);
 		await writeFile(join(DIST, "index.html"), html);
 		console.log("  ✓ index.html (Getting Started)");
 		console.log(`\n\x1b[33mNo content found. Create site.yaml or content/ directory.\x1b[0m`);
 		return;
 	}
 
+	if (config.mode === "slides") {
+		const html = await renderSlidesIndex(template, files, provenance, config, theme, plugins);
+		await writeFile(join(DIST, "index.html"), html);
+		console.log(`  ✓ index.html (slides mode, ${files.length} source files)`);
+		await generateAIAccessibility(DIST, files, config, provenance);
+		console.log(`\n\x1b[32mBuild complete! Output in ${OUT_DIR}/\x1b[0m`);
+		console.log(`\nTo view locally: open ${OUT_DIR}/index.html`);
+		return;
+	}
+
 	for (const file of files) {
 		const html = await renderFile(
 			file.path,
@@ -386,6 +526,7 @@ async function buildSite() {
 			provenance,
 			config,
 			theme,
+			plugins,
 		);
 
 		// Create output path
@@ -403,7 +544,16 @@ async function buildSite() {
 		if (homePath) {
 			try {
 				await stat(homePath);
-				const homeHtml = await renderFile(homePath, "", template, files, provenance, config, theme);
+				const homeHtml = await renderFile(
+					homePath,
+					"",
+					template,
+					files,
+					provenance,
+					config,
+					theme,
+					plugins,
+				);
 				await writeFile(join(DIST, "index.html"), homeHtml);
 				console.log(`  ✓ index.html (from ${config.home})`);
 			} catch {
@@ -417,6 +567,7 @@ async function buildSite() {
 					provenance,
 					config,
 					theme,
+					plugins,
 				);
 				await writeFile(join(DIST, "index.html"), indexHtml);
 				console.log("  ✓ index.html");
@@ -433,6 +584,7 @@ async function buildSite() {
 			provenance,
 			config,
 			theme,
+			plugins,
 		);
 		await writeFile(join(DIST, "index.html"), indexHtml);
 		console.log("  ✓ index.html");