kitfly 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to Kitfly are documented here.
 
+## [0.2.3] - 2026-02-17
+
+### Added
+
+- Content profiles: `--profile` flag and `KITFLY_PROFILE` env var for single-source multi-audience filtering via frontmatter `profile:` tags
+- Data-driven bindings: `{{ key }}` value substitution and `{{ snippet:name }}` block injection from YAML/JSON data files bound via `data:` frontmatter
+- Pre-build hooks: `prebuild:` commands in site.yaml that run before dev/build/bundle with watch-mode reruns
+- Built-in formatters: `dollar`, `number`, `percent`, `round(n)`, `upper`, `lower` with pipe chaining (`{{ key | round(0) | dollar }}`)
+- Optional schema validation for data files (JSON Schema structural checks)
+- ADR-0006: Data-Driven Content architecture decision
+- "Kitsite" terminology and "What's a Kitsite?" section in README
+
+### Fixed
+
+- Windows cross-platform compatibility: launcher script install (no symlinks), browser open dispatch, MSYS `/c/...` path normalization
+- Profile filtering backward compatibility when no profiles configured and no active profile selected
+- `KITFLY_PROFILE` environment variable propagation through kitfly CLI entrypoints
+- YAML parser: block scalar (`|`/`>`) support for data file snippets
+- YAML parser: direct list-item block scalars, chomping/indent indicator handling
+- YAML parser: reject malformed block scalar headers (`|abc`, `>foo`) instead of silent empty strings
+
+### Docs
+
+- Windows contributor setup guide in docs/development.md
+- Development docs table alignment fix
+
+### Generator guidance (from dogfooding)
+
+- `pages[].path` in data files must be relative to site root including `content/` prefix (e.g. `content/product/pricing.md`, not `product/pricing.md`)
+- Generators must emit every snippet the template references, even if empty — the template is the contract
+- `percent` formatter expects a decimal ratio (0.0–1.0), not an already-computed percentage
+- Use JSON for generator-produced data files; reserve YAML for hand-authored data where readability matters
+- Recommended layout: raw input in `data/raw/`, kitfly data files in `data/`
+
+## [0.2.2] - 2026-02-16
+
+### Added
+
+- `slides-charts-lite` plugin: bar/line/pie charts via Chart.js 4.4.7 CDN with fenced `chart` code blocks
+- `latex` plugin: math typesetting via KaTeX 0.16.21 CDN ($inline$, $$display$$, fenced `math` blocks)
+- `brief` template: external-audience product documentation with 4 sections and starter content
+- Footer logo: `footer.logo`, `logoUrl`, `logoAlt`, `logoHeight` fields for image logos in the footer ribbon
+- Dark mode logo variants: `brand.logoDark` and `footer.logoDark` fields with CSS show/hide swap (no JS)
+- Hierarchical slide navigation: nested nav with collapsible groups for decks with subfolder content
+- Branding guide (`content/guide/branding.md`): canonical reference for header logos, footer logos, dark mode variants
+
+### Fixed
+
+- Plugin template injection: `$` replacement corruption that broke LaTeX delimiter rendering
+- Plugin CDN loader: path resolution for LaTeX plugin assets
+
+### Docs
+
+- Configuration reference updated with footer logo and dark mode logo fields
+- All templates (handbook, runbook, brief, deck) updated with expanded Brand Assets documentation
+
 ## [0.2.1] - 2026-02-15
 
 ### Added

package/README.md

@@ -31,21 +31,36 @@ Alternative: `npm install -g kitfly` (still requires Bun, because the CLI runs w
 
 No global install: `bunx kitfly --version`
 
-Note: `bun`/`npm` installs the latest published release. If you’re reading `main` before a release is cut, clone this repo for the newest features.
+Note: `bun`/`npm` installs the latest published release. If you're reading `main` before a release is cut, clone this repo for the newest features.
+
+**Don't need the CLI?** `kitfly init` creates a [standalone site](#create-a-standalone-site-recommended) that runs with just Bun — no kitfly binary required after setup.
 
 For contributor/development setup, see [docs/development.md](docs/development.md).
 
 ---
 
+## What's a Kitsite?
+
+Any site created or managed by kitfly is a **kitsite** — a self-contained workspace with your content, configuration, and (optionally) build scripts. A kitsite can operate in different **modes**:
+
+| Mode     | What it produces                  | Created with                          |
+| -------- | --------------------------------- | ------------------------------------- |
+| `docs`   | Documentation site (default)      | `kitfly init my-docs`                 |
+| `slides` | Fixed-aspect slide deck (v0.2.0+) | `kitfly init my-deck --template deck` |
+
+Every kitsite has the same structure: a `content/` directory with your markdown, a `site.yaml` for configuration, and static output you can host anywhere or bundle into a single HTML file. Standalone kitsites (created with `kitfly init`) include their own build scripts and run with just Bun — no kitfly CLI required after setup.
+
+---
+
 ## Three Ways to Use Kitfly
 
-| Approach                  | Best For      | What You Get                                   |
-| ------------------------- | ------------- | ---------------------------------------------- |
-| **`kitfly init`**         | New projects  | Standalone site with your own copy of the code |
-| **`kitfly dev ./folder`** | Existing docs | Quick preview without changing anything        |
-| **Clone this repo**       | Contributors  | The kitfly engine itself                       |
+| Approach                  | Best For      | What You Get                                      |
+| ------------------------- | ------------- | ------------------------------------------------- |
+| **`kitfly init`**         | New projects  | Standalone kitsite with your own copy of the code |
+| **`kitfly dev ./folder`** | Existing docs | Quick preview without changing anything           |
+| **Clone this repo**       | Contributors  | The kitfly engine itself                          |
 
-### Create a Standalone Site (Recommended)
+### Create a Standalone Kitsite (Recommended)
 
 ```bash
 kitfly init my-docs
@@ -63,7 +78,7 @@ bun install
 bun run dev
 ```
 
-You get a complete, self-contained site: rendering code, template, styles, config. It's yours — modify it, version it, own it. No kitfly CLI required after setup.
+You get a complete, self-contained kitsite: rendering code, template, styles, config. It's yours — modify it, version it, own it. No kitfly CLI required after setup.
 
 ### Preview Existing Docs
 
@@ -149,7 +164,7 @@ Or just drop markdown files in `content/` — sections auto-discover.
 
 ## Plugins
 
-Plugins are optional CSS/JS add-ons (kept out of core) that you enable per-site.
+Plugins are optional CSS/JS add-ons (kept out of core) that you enable per-kitsite.
 
 - Config: `kitfly.plugins.yaml`
 - Versions are pinned (`name@x.y.z`)
@@ -163,7 +178,7 @@ See `content/reference/plugins.md` for the contract and examples.
 
 > **Rule of thumb**: If it can't be done with CSS, vanilla JS under 50 lines, or a marked plugin, it doesn't belong here.
 
-Kitfly is intentionally limited. The goal is a doc site that stays simple and maintainable. When you outgrow it, migrate — your content is just markdown.
+Kitfly is intentionally limited. The goal is a kitsite that stays simple and maintainable. When you outgrow it, migrate — your content is just markdown.
 
 ---
 

package/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.3

package/dist/_raw/content/guide/branding.md

@@ -0,0 +1,146 @@
+---
+title: Branding
+description: Configure header logos, footer logos, and dark mode variants
+---
+
+# Branding
+
+Kitfly sites display your brand in two locations: the **header** (sidebar logo + site title) and the **footer ribbon** (optional logo, copyright, links). Both support light/dark mode variants.
+
+## Header Logo
+
+The header logo appears in the sidebar above the navigation. Configure it in `site.yaml`:
+
+```yaml
+brand:
+  name: "My Project"
+  url: "/"
+  logo: "assets/brand/logo.png"
+```
+
+The logo renders inside a bounded slot that preserves aspect ratio. Both square icons and wide wordmarks work — set `logoType` to tell kitfly which you're using:
+
+```yaml
+brand:
+  logo: "assets/brand/logo.png"
+  logoType: "icon" # square mark (default)
+```
+
+```yaml
+brand:
+  logo: "assets/brand/wordmark.svg"
+  logoType: "wordmark" # wide logo
+```
+
+| Breakpoint       | Max Height | Max Width |
+| ---------------- | ---------- | --------- |
+| Desktop          | 64px       | 180px     |
+| Tablet (≤1024px) | 56px       | 150px     |
+| Mobile (≤768px)  | 48px       | 130px     |
+
+SVG and PNG formats are supported. For SVGs, ensure the `viewBox` is tightly cropped to the artwork.
+
+If the logo image is missing or fails to load, kitfly falls back to displaying the first letter of your brand name.
+
+## Footer Logo
+
+Add a logo to the footer ribbon — typically a parent company, client, or partner logo that differs from the header brand:
+
+```yaml
+footer:
+  logo: "assets/brand/footer-logo.png"
+```
+
+The footer logo renders at the leading edge of the ribbon, before the version and publish date.
+
+### Footer Logo Options
+
+| Field        | Default                      | Description                         |
+| ------------ | ---------------------------- | ----------------------------------- |
+| `logo`       | _(none)_                     | Path to footer logo image           |
+| `logoUrl`    | _(none)_                     | Make the logo a clickable link      |
+| `logoAlt`    | Copyright text or brand name | Alt text for accessibility          |
+| `logoHeight` | `20`                         | Max height in pixels (range: 10-40) |
+
+```yaml
+footer:
+  logo: "assets/brand/footer-logo.png"
+  logoUrl: "https://example.com"
+  logoAlt: "Example Corp"
+  logoHeight: 24
+```
+
+If no `footer.logo` is set, the footer renders as text only (version, copyright, links, attribution) — no change from the default.
+
+## Dark Mode Variants
+
+By default, kitfly auto-adjusts logo brightness in dark mode using a CSS filter. This works for many logos but can distort brand colors or fail on dark logos with transparent backgrounds.
+
+For precise control, provide a separate dark mode image:
+
+### Header
+
+```yaml
+brand:
+  logo: "assets/brand/logo.png"
+  logoDark: "assets/brand/logo-dark.png"
+```
+
+### Footer
+
+```yaml
+footer:
+  logo: "assets/brand/footer-logo.png"
+  logoDark: "assets/brand/footer-logo-dark.png"
+```
+
+### How It Works
+
+When `logoDark` is set, kitfly emits both images and uses CSS to show the correct one based on the active theme. No JavaScript is involved — the swap is instant on theme toggle.
+
+| Configuration       | Light Mode | Dark Mode                         |
+| ------------------- | ---------- | --------------------------------- |
+| `logo` only         | Shows logo | Shows logo with brightness filter |
+| `logo` + `logoDark` | Shows logo | Shows logoDark (no filter)        |
+
+### Recommendations
+
+- Use the **single logo** approach when your logo works on both light and dark backgrounds (e.g. a colorful icon on transparent background)
+- Use **light + dark variants** when your logo has a specific background assumption (e.g. dark wordmark that disappears on dark backgrounds)
+- Keep both variants at the **same dimensions** so the layout doesn't shift on theme toggle
+- SVG is ideal for both variants — resolution-independent and small file size
+
+## Recommended Asset Files
+
+| Asset               | Location                            | Size / Format       |
+| ------------------- | ----------------------------------- | ------------------- |
+| Logo (light)        | `assets/brand/logo.png`             | 200x50px or SVG     |
+| Logo (dark)         | `assets/brand/logo-dark.png`        | Same as logo        |
+| Footer logo (light) | `assets/brand/footer-logo.png`      | Max height 20-40px  |
+| Footer logo (dark)  | `assets/brand/footer-logo-dark.png` | Same as footer logo |
+| Favicon             | `assets/brand/favicon.ico`          | 32x32px             |
+
+## Full Example
+
+A site with separate header and footer logos, both with dark mode variants:
+
+```yaml
+# site.yaml
+title: "Product Brief"
+
+brand:
+  name: "Product Name"
+  url: "/"
+  logo: "assets/brand/product-logo.png"
+  logoDark: "assets/brand/product-logo-dark.png"
+  logoType: "wordmark"
+
+footer:
+  copyright: "© 2026 Parent Company, Inc."
+  copyrightUrl: "https://example.com"
+  logo: "assets/brand/parent-logo.png"
+  logoDark: "assets/brand/parent-logo-dark.png"
+  logoAlt: "Parent Company"
+  logoHeight: 20
+  attribution: true
+```

package/dist/_raw/content/guide/data-driven-content.md

@@ -0,0 +1,204 @@
+---
+title: "Data-Driven Content"
+description: "Use data bindings and generators to build pages from structured data"
+last_updated: "2026-02-17"
+---
+
+# Data-Driven Content
+
+Some pages are driven by structured data — pricing tables, team rosters, metrics dashboards, product catalogs. Data-driven content lets you separate prose (markdown), computation (generators), and data (YAML/JSON files) so each layer does what it's good at.
+
+## When to use this
+
+Use data bindings when:
+
+- The same values appear in multiple places on a page (DRY)
+- A generator computes values that appear in prose (pricing math, discount brackets)
+- Tables or blocks are produced by scripts and injected into narrative content
+
+Don't use data bindings when:
+
+- The page is pure prose with no external data
+- You need loops, conditionals, or expressions — use a generator to produce the final markdown instead
+
+## How it works
+
+```
+raw input → generator → data file → kitfly bindings → markdown → HTML
+```
+
+1. A **generator** (any script) reads raw input and writes a data file
+2. A **data file** (YAML or JSON) declares globals, per-page values, and snippets
+3. **Markdown templates** use `{{ key }}` and `{{ snippet:name }}` placeholders
+4. Kitfly resolves bindings at build time, before markdown rendering
+
+## Data file structure
+
+```yaml
+# data/pricing.yaml
+globals:
+  company: "Acme Corp"
+  baseline_rate: "200"
+  credit_validity: "12"
+
+pages:
+  - path: content/product/pricing.md
+    inject:
+      hero: "Implementation and operating costs"
+      discount_range: "5–20%"
+    snippets:
+      - slot: pricing-table
+        content: |
+          | Tier | Price | Features |
+          |------|-------|----------|
+          | Basic | $10/mo | Essentials |
+          | Pro | $50/mo | Full access |
+```
+
+**Path convention:** `pages[].path` must be relative to site root including the `content/` prefix. Use `content/product/pricing.md`, not `product/pricing.md`. Kitfly's error messages include the expected path if there's a mismatch.
+
+### Resolution order
+
+For `{{ key }}`: page `inject` first, then `globals`. Page-level values shadow globals on key collision.
+
+For `{{ snippet:name }}`: matched by `slot` name from the page's `snippets` array.
+
+## Binding syntax
+
+### Value substitution
+
+```markdown
+Implementation rate: **{{ baseline_rate | dollar }}/hour**
+
+Credits valid for {{ credit_validity }} months.
+```
+
+### Snippet injection
+
+```markdown
+## Pricing Tiers
+
+{{ snippet:pricing-table }}
+```
+
+Snippets are injected verbatim as markdown. After all bindings resolve, the full document passes through the markdown renderer as usual.
+
+## Formatters
+
+Apply with pipe syntax. Chaining composes left to right: `{{ key | round(0) | dollar }}`.
+
+| Formatter  | Input       | Output   | Notes                                       |
+| ---------- | ----------- | -------- | ------------------------------------------- |
+| `dollar`   | `"1500"`    | `$1,500` | USD format; cents only if fractional        |
+| `number`   | `"2500"`    | `2,500`  | Comma-separated                             |
+| `percent`  | `"0.15"`    | `15%`    | **Input must be a decimal ratio (0.0–1.0)** |
+| `round(n)` | `"3.14159"` | `3.14`   | Round to n decimal places                   |
+| `upper`    | `"hello"`   | `HELLO`  | Uppercase                                   |
+| `lower`    | `"HELLO"`   | `hello`  | Lowercase                                   |
+
+**`percent` expects a decimal ratio.** `"0.15"` becomes `15%`. If your generator already computes integer percentages (like `"5"` for 5%), store them as pre-formatted strings (`"5%"`) and don't pipe through `percent` — that would yield `500%`.
+
+All formatters are pure functions: string in, string out. The set is closed — adding a formatter requires a kitfly code change.
+
+## Error handling
+
+Kitfly fails loud on binding errors. These are build errors, not warnings:
+
+| Condition               | Error message                                            |
+| ----------------------- | -------------------------------------------------------- |
+| Data file not found     | `data file not found: data/pricing.yaml`                 |
+| Unresolved `{{ key }}`  | `unresolved binding "key" in content/product/pricing.md` |
+| Unknown snippet slot    | `unknown snippet "name" in content/product/pricing.md`   |
+| Formatter parse failure | `dollar formatter: "hello" is not a number ...`          |
+| Unknown formatter       | `unknown formatter "custom_fn" ...`                      |
+| Path escapes kitsite    | `data path escapes kitsite: ../secrets/data.yaml`        |
+
+## Pre-build hooks
+
+Declare generators in `site.yaml`:
+
+```yaml
+prebuild:
+  - command: "bun run scripts/generate-pricing-data.ts"
+    watch: ["data/raw/pricing-input.json"]
+  - command: "bun run scripts/generate-team-data.ts"
+```
+
+| Context          | When hooks run                                        |
+| ---------------- | ----------------------------------------------------- |
+| `bun run dev`    | Once at startup, then again when watched files change |
+| `bun run build`  | Once before build starts                              |
+| `bun run bundle` | Once before bundle starts                             |
+
+Hooks run sequentially in declared order. A non-zero exit code halts the build with the hook's stderr as error context.
+
+### Watch flow in dev mode
+
+```
+watched file changes → re-run matching hook → hook writes to data/ → data/ change triggers rebuild
+```
+
+Content changes (edits to markdown) do NOT re-run hooks. Only watched file changes trigger hooks.
+
+## Schema validation (optional)
+
+If `data/pricing.schema.json` exists alongside `data/pricing.yaml`, kitfly validates the data at build time. JSON Schema structural checks cover required fields, value types, and pattern constraints.
+
+Missing schema files are not an error — validation is opt-in.
+
+## Generator best practices
+
+These patterns emerged from real-world usage and apply to any non-trivial generator.
+
+### The template is the contract
+
+Every `{{ snippet:X }}` in a markdown template means the generator must always emit a snippet named `X` in the data file, even if the content is empty. Kitfly treats missing snippets as build errors — by design.
+
+If a section is conditionally relevant (e.g. an implementation-tiers table that only applies to multi-tier configurations), the generator should emit the snippet with empty string content when the section doesn't apply. The blank line in the rendered output is acceptable and avoids conditional logic in the template.
+
+```yaml
+# Generator always emits this, even when single-tier
+snippets:
+  - slot: implementation-tiers
+    content: ""
+```
+
+### Use JSON for generator output
+
+Generators should write JSON data files. `JSON.stringify` is deterministic in every language, there's no quoting ambiguity, and multiline strings use unambiguous `\n` escapes.
+
+Reserve YAML for hand-authored data files (team rosters, simple config) where human readability matters.
+
+### Separate raw input from kitfly data
+
+Keep generator source files in `data/raw/` and kitfly data files in `data/`:
+
+```
+data/
+  raw/
+    pricing-input.json    ← generator reads this
+    team.csv              ← generator reads this
+  pricing.json            ← generator writes this (kitfly reads it)
+  team.json               ← generator writes this (kitfly reads it)
+```
+
+This prevents naming collisions and makes the data flow visible. The `prebuild:` hook `watch:` patterns point at `data/raw/` sources, and kitfly reads the generated files from `data/`.
+
+### Generator language
+
+Generators can be written in any language. Kitfly runs them as shell commands. The motivating use case was a Python generator in an otherwise TypeScript/Bun ecosystem — pre-build hooks eliminate the manual step and integrate it into the dev/build pipeline regardless of language.
+
+## Interaction with content profiles
+
+Data bindings and content profiles are independent features that compose naturally:
+
+- Profile filtering runs first (after file collection, before rendering)
+- Data binding resolution runs second (after reading markdown, before markdown rendering)
+- A page excluded by profile filtering is never read, so its bindings are never resolved
+- `KITFLY_PROFILE` is passed to pre-build hooks so generators can adapt output per profile
+
+## Backwards compatibility
+
+- Pages without `data:` frontmatter: no binding resolution, literal `{{ }}` passes through unchanged
+- Sites without `prebuild:` in site.yaml: no hooks run, zero overhead
+- Sites without a `data/` directory: no binding resolution, zero overhead