kitfly 0.2.0 → 0.2.3

package/dist/_raw/content/reference/configuration.md

@@ -1,7 +1,7 @@
 ---
 title: "Configuration"
 description: "Customize your kitfly site"
-last_updated: "2026-02-03"
+last_updated: "2026-02-17"
 ---
 
 # Configuration
@@ -59,6 +59,18 @@ docroot: "content"
 
 See [Folder Structure](structure.html) for details.
 
+### dataroot (v0.2.3+)
+
+Data directory used for frontmatter `data:` bindings.
+
+```yaml
+dataroot: "data"
+```
+
+Default: `data`
+
+`dataroot` must resolve inside the site root (no `../`, no absolute paths). Data files are loaded at build time and are not copied into output pages.
+
 ### title
 
 Site title. Appears in browser tab and header.
@@ -100,10 +112,13 @@ brand:
   name: "My Project" # Text in header
   url: "/" # Logo link
   logo: "assets/brand/my-logo.png" # Sidebar logo image
+  logoDark: "assets/brand/my-logo-dark.png" # Dark mode logo (optional)
   favicon: "assets/brand/favicon-32.png" # Browser tab icon
   external: true # Open in new tab (optional)
 ```
 
+When `logoDark` is set, kitfly shows it in dark mode instead of applying the default brightness filter. See the [Branding](/content/guide/branding) guide for details on dark mode variants.
+
 The logo renders inside a bounded slot that preserves aspect ratio:
 
 | Breakpoint       | Max Height | Max Width |
@@ -139,7 +154,7 @@ sections:
 | ---------- | ------- | ----- | ------------------------------------------------- |
 | `maxDepth` | 4       | 1–10  | How many directory levels to scan for `.md` files |
 
-Deeper sections produce hierarchical sidebar navigation with collapsible groups. Set a lower `maxDepth` for sections where you want a flatter sidebar.
+Deeper sections produce hierarchical sidebar navigation with collapsible groups. This applies to both docs and slides modes — slide decks with subfolder content get nested, collapsible nav while keeping `#slide-N` hash navigation. Set a lower `maxDepth` for sections where you want a flatter sidebar.
 
 **Explicit files:** For precise control over which files appear (bypasses auto-discovery):
 
@@ -150,6 +165,51 @@ sections:
     files: ["README.md", "CHANGELOG.md"]
 ```
 
+### profiles (v0.2.3+)
+
+Named content profiles for single-source multi-audience filtering.
+
+```yaml
+profiles:
+  alpha:
+    description: "Includes alpha-tagged content"
+    include:
+      tags: ["alpha"]
+  beta:
+    description: "Includes beta-tagged content"
+    include:
+      tags: ["beta"]
+```
+
+Activate a profile via CLI flag or environment variable:
+
+```bash
+kitfly dev ./mysite --profile alpha
+KITFLY_PROFILE=beta kitfly build ./mysite
+```
+
+Files with a matching `profile:` frontmatter tag are included. Files without a `profile:` field are always included. Tagged files are excluded when no profile is active or when the active profile doesn't match.
+
+Sites without `profiles:` in site.yaml are completely unaffected — adding the field has no effect until a profile is explicitly activated.
+
+### prebuild (v0.2.3+)
+
+Run generator commands before `dev`, `build`, and `bundle`.
+
+```yaml
+prebuild:
+  - command: "bun run scripts/generate-pricing-data.ts"
+    watch: ["data/raw/pricing-input.json"]
+  - command: "bun run scripts/generate-team-data.ts"
+```
+
+Rules:
+
+- Hooks run sequentially in declared order.
+- Non-zero exit halts the command with hook stderr.
+- In dev mode, `watch:` patterns re-run matching hooks on file changes.
+- Kitfly sets `KITFLY_SITE_ROOT`, `KITFLY_DATA_DIR`, `KITFLY_BUILD_MODE`, and `KITFLY_PROFILE` (when active).
+
 ### footer
 
 Footer has three zones: provenance (left), copyright and links (center), and Kitfly attribution (right). Each field is independent — setting one does not affect the others.
@@ -165,6 +225,11 @@ v0.1.1 · Published 2026-02-10     © 2026 Acme Inc. · acme.com     Built with
 | `copyrightUrl` | _(none)_                         | Makes the copyright text a clickable link |
 | `links`        | Your `brand.url` shown as a link | Links after the copyright text (max 10)   |
 | `attribution`  | `true`                           | "Built with Kitfly" on the right          |
+| `logo`         | _(none)_                         | Image logo in the footer-left position    |
+| `logoDark`     | _(none)_                         | Dark mode variant of the footer logo      |
+| `logoUrl`      | _(none)_                         | Makes the footer logo a clickable link    |
+| `logoAlt`      | Copyright text or brand name     | Alt text for the footer logo              |
+| `logoHeight`   | `20`                             | Max height of footer logo in pixels       |
 
 **Common case: product name differs from copyright holder.** The default copyright uses `brand.name`, which is your product title (shown in the header). If your legal entity is different, override it:
 
@@ -205,6 +270,19 @@ When `links` is set, it replaces the default brand URL link. When `links` is omi
 
 Set `footer.attribution: false` to remove the "Built with Kitfly" text from the footer entirely.
 
+**Footer logo** — add an image to the footer ribbon (e.g. a parent company logo):
+
+```yaml
+footer:
+  logo: "assets/brand/footer-logo.png"
+  logoDark: "assets/brand/footer-logo-dark.png"
+  logoUrl: "https://example.com"
+  logoAlt: "Example Corp"
+  logoHeight: 24
+```
+
+The footer logo renders at the leading edge of the ribbon, before provenance info. All footer logo fields are optional — if `logo` is omitted, the footer renders as text only. See the [Branding](/content/guide/branding) guide for full details.
+
 ### theme layout (`theme.yaml`)
 
 `theme.yaml` can override layout variables, including sidebar width.
@@ -232,11 +310,71 @@ last_updated: "2026-02-03"
 # Content starts here
 ```
 
-| Field          | Purpose                         |
-| -------------- | ------------------------------- |
-| `title`        | Page title (overrides filename) |
-| `description`  | Meta description                |
-| `last_updated` | Shown in page footer            |
+| Field          | Purpose                                                             |
+| -------------- | ------------------------------------------------------------------- |
+| `title`        | Page title (overrides filename)                                     |
+| `description`  | Meta description                                                    |
+| `last_updated` | Shown in page footer                                                |
+| `data`         | Data file for `{{ key }}` / `{{ snippet:name }}` bindings (v0.2.3+) |
+| `profile`      | Profile tag(s) for audience filtering (v0.2.3+)                     |
+
+### `data` frontmatter (v0.2.3+)
+
+Bind a page to a data file for value substitution and snippet injection:
+
+```yaml
+---
+title: "Pricing"
+data: "data/pricing.yaml"
+---
+```
+
+The `data:` path is relative to site root. The data file uses a structured format:
+
+```yaml
+globals:
+  company: "Acme Corp"
+  baseline_rate: "200"
+
+pages:
+  - path: content/product/pricing.md
+    inject:
+      hero: "Implementation and operating costs"
+    snippets:
+      - slot: pricing-table
+        content: |
+          | Tier | Price |
+          |------|-------|
+          | Basic | $10/mo |
+```
+
+**Path convention:** `pages[].path` must be relative to site root including the `content/` prefix — e.g. `content/product/pricing.md`, not `product/pricing.md`.
+
+In the markdown body, use `{{ key }}` for value substitution and `{{ snippet:name }}` for block injection. Formatters apply with pipe syntax: `{{ baseline_rate | dollar }}`. See the [Data-Driven Content](/content/guide/data-driven-content) guide for the full formatter reference and generator patterns.
+
+Pages without `data:` frontmatter are completely unaffected — literal `{{ }}` text passes through as-is.
+
+### `profile` frontmatter (v0.2.3+)
+
+Tag a file for profile-based filtering:
+
+```yaml
+---
+title: "Engagement Timeline"
+profile: alpha
+---
+```
+
+Multiple profiles:
+
+```yaml
+---
+title: "Shared Appendix"
+profile: [alpha, beta]
+---
+```
+
+Files without a `profile:` field are always included regardless of which profile is active. See `profiles` in Settings above.
 
 ## No Configuration
 

package/dist/_raw/content/reference/environment-variables.md

@@ -1,7 +1,7 @@
 ---
 title: "Environment Variables"
 description: "A beginner-friendly primer (with copy-paste examples)"
-last_updated: "2026-02-12"
+last_updated: "2026-02-17"
 ---
 
 # Environment Variables
@@ -58,6 +58,31 @@ If you use one:
 - make sure it is gitignored
 - consider adding a `.env.example` with placeholder values (safe to commit)
 
+## Kitfly environment variables (v0.2.3+)
+
+### `KITFLY_PROFILE`
+
+Activate a content profile without the `--profile` CLI flag:
+
+```bash
+KITFLY_PROFILE=alpha kitfly build ./mysite
+```
+
+Equivalent to `kitfly build ./mysite --profile alpha`.
+
+### Pre-build hook variables
+
+Kitfly sets these before running each `prebuild:` hook:
+
+| Variable            | Value                           | Example                     |
+| ------------------- | ------------------------------- | --------------------------- |
+| `KITFLY_SITE_ROOT`  | Absolute path to kitsite root   | `/Users/me/my-docs`         |
+| `KITFLY_DATA_DIR`   | Data directory relative to root | `data/`                     |
+| `KITFLY_BUILD_MODE` | Current build mode              | `dev`, `build`, or `bundle` |
+| `KITFLY_PROFILE`    | Active content profile (if any) | `alpha`                     |
+
+These allow generators to adapt behavior per build context — for example, a generator might skip expensive API calls in `dev` mode or produce different output per profile.
+
 ## Quick troubleshooting
 
 - If a command says a variable is missing, print it:

package/dist/_raw/content/reference/glossary.md

@@ -1,7 +1,7 @@
 ---
 title: "Glossary"
 description: "Quick definitions for common Kitfly terms"
-last_updated: "2026-02-12"
+last_updated: "2026-02-17"
 ---
 
 # Glossary
@@ -90,3 +90,27 @@ A named value provided to commands and apps by your shell or host platform (ofte
 ## Secret
 
 A sensitive value (token/key/password) that should not be committed to git and should be stored in a secret manager or environment variable.
+
+## Profile
+
+A named content filter activated via `--profile` or `KITFLY_PROFILE`. Files tagged with `profile:` in frontmatter are only included when their profile is active. Enables single-source multi-audience workflows.
+
+## Kitsite
+
+The workspace Kitfly renders: typically contains `site.yaml`, content files, and optional `data/` + `scripts/`.
+
+## Generator
+
+A script that transforms external data into Kitfly’s file contract (usually writes `data/*.yaml` or `data/*.json`).
+
+## Data binding
+
+Build-time substitution from a bound data file into markdown (`{{ key }}` and `{{ snippet:name }}`).
+
+## Formatter
+
+A deterministic value transform in bindings (for example `dollar`, `number`, `percent`, `round(n)`, `upper`, `lower`).
+
+## Snippet
+
+A named markdown block in a data file that can be injected with `{{ snippet:name }}`.

package/dist/_raw/content/reference/key-concepts.md

@@ -1,7 +1,7 @@
 ---
 title: "Key Concepts"
 description: "Mental models for how Kitfly works"
-last_updated: "2026-02-12"
+last_updated: "2026-02-17"
 ---
 
 # Key Concepts
@@ -86,7 +86,7 @@ If you do: `theme.yaml` is your main “make it mine” knob.
 Kitfly can render the same Markdown content in two layouts:
 
 - **docs** (default): scrolling pages optimized for reading
-- **slides**: fixed-aspect “one page at a time” slides with keyboard navigation
+- **slides**: fixed-aspect "one page at a time" slides with keyboard navigation
 
 Slides mode is configured in `site.yaml`:
 
@@ -95,12 +95,40 @@ mode: slides
 aspect: "16/9"
 ```
 
+In both modes, organizing content into subfolders produces hierarchical sidebar navigation with collapsible groups. In slides mode, the nav links remain `#slide-N` hash anchors — the tree structure is visual grouping only.
+
 ## Assets
 
 Kitfly will serve and bundle common “content-adjacent” assets referenced from Markdown, like images and PDFs.
 
 Rule of thumb: if it lives next to your docs, Kitfly tries to do the right thing.
 
+## Content profiles (v0.2.3+)
+
+Profiles let you produce multiple audience-specific outputs from a single kitsite. Tag files with `profile:` in frontmatter and activate a profile via `--profile` flag or `KITFLY_PROFILE` env var.
+
+- Files without `profile:` are always included (the common case).
+- Tagged files only appear when their profile is active.
+- No active profile = only untagged content.
+
+This is a startup parameter, not a runtime toggle — changing profiles requires restarting the dev server.
+
+## Data bindings (v0.2.3+)
+
+A page can opt into build-time bindings by setting `data:` in frontmatter.
+
+- `{{ key }}` resolves scalar values from a data file.
+- `{{ snippet:name }}` injects a named markdown block.
+- Formatters like `dollar`, `number`, `percent`, `round(n)`, `upper`, `lower` apply with pipe syntax.
+
+No loops/conditionals are supported in bindings. If you need logic, use a generator script and write data files before render.
+
+## Pre-build hooks (v0.2.3+)
+
+`prebuild:` commands in `site.yaml` run before `dev`, `build`, and `bundle`.
+
+Use hooks for generators (CSV/API/etc. to `data/*.yaml` or `data/*.json`). In dev mode, hook `watch:` patterns can re-run hooks when source files change.
+
 ## Provenance
 
 Kitfly can emit provenance information (version/build date/git info) so you can answer “what did we ship?”.

package/dist/_raw/content/reference/plugins.md

@@ -26,6 +26,20 @@ plugins:
 
 Canonical plugins are referenced as pinned strings: `name@x.y.z`.
 
+### Canonical plugins (v0.2.2)
+
+- `callouts@0.2.0` - styled NOTE/TIP/INFO/WARNING/DANGER blockquotes
+- `slides-visuals@0.2.1` - slide widgets + figures via `:::` blocks (`slides` mode only)
+- `latex@0.2.2` - KaTeX math rendering for `$...$`, `$$...$$`, and fenced `math` blocks
+- `slides-charts-lite@0.2.2` - bar/line/pie charts from fenced `chart` blocks (`slides` mode only)
+
+Example:
+
+```yaml
+plugins:
+  - latex@0.2.2
+```
+
 ## Registry + assets
 
 Canonical plugins come from a registry file:

package/dist/_raw/content/reference/slides-authoring-guidelines.md

@@ -0,0 +1,129 @@
+---
+title: "Slides Authoring Guidelines"
+description: "Practical density and layout rules for reliable Kitfly slides"
+last_updated: "2026-02-15"
+---
+
+# Slides Authoring Guidelines
+
+This page is for slide authors and AI agents generating slide content.
+
+Goal: avoid common layouts that look broken but are actually content-density issues.
+
+## Quick rules
+
+- Keep vertical visuals short. If a slide is tall and busy, trim items before adding more styling.
+- Treat highlighted (`.accent`) blocks as emphasis, not interaction.
+- Scroll in slides mode is allowed for dense content. Prefer no scroll for presentation slides.
+
+## DF-006: Single `.accent` in `.block-grid` looks like a tab
+
+### Problem
+
+When one block in a row is accented and others are not, users read it as a selected tab and expect click behavior.
+
+### Do this
+
+- In one grid row, accent all blocks or accent none.
+- If you need real tabs, treat that as a future widget (`slides-widgets`), not static blocks.
+
+### Avoid this
+
+```html
+<div class="block-grid cols-3">
+  <div class="block">Backend</div>
+  <div class="block accent">Platform</div>
+  <div class="block">SRE</div>
+</div>
+```
+
+### Prefer this
+
+```html
+<div class="block-grid cols-3">
+  <div class="block accent">Backend</div>
+  <div class="block accent">Platform</div>
+  <div class="block accent">SRE</div>
+</div>
+```
+
+or
+
+```html
+<div class="block-grid cols-3">
+  <div class="block">Backend</div>
+  <div class="block">Platform</div>
+  <div class="block">SRE</div>
+</div>
+```
+
+## DF-007: `block-flow.vertical` can overflow at 4/3
+
+### Problem
+
+`.block-flow.vertical` (HTML: `class="block-flow vertical"`) with 4 steps can exceed the visible frame at `4/3`.
+
+### Do this
+
+- At `4/3`: limit vertical flows to 3 blocks.
+- At `16/9`: 4 blocks is usually fine.
+- If the slide also has extra text/callouts, reduce steps further.
+
+### Guidance
+
+- If you must keep all steps, scroll is acceptable.
+- For presentation-first slides, split into two slides instead.
+
+### Example target
+
+```html
+<div class="block-flow vertical">
+  <div class="block">1. Intake</div>
+  <div class="block">2. Validate</div>
+  <div class="block">3. Ship</div>
+</div>
+```
+
+## DF-014: `timeline-vertical` + callout can clip at 16/9
+
+### Problem
+
+A 5-event vertical timeline plus a callout often exceeds the frame at `16/9`.
+
+### Do this
+
+- At `16/9`: keep `timeline-vertical` to 4 events when the slide also has a callout.
+- At `4/3`: keep to 3 events with a callout.
+- If you need all events, remove the callout or move it to a follow-up slide.
+
+### Example (safe with callout)
+
+```text
+:::timeline-vertical
+events:
+- label: "Detect"
+  date: "09:15"
+- label: "Triage"
+  date: "09:24"
+- label: "Mitigate"
+  date: "09:42"
+- label: "Recover"
+  date: "10:08"
+:::
+
+> WARNING: External API fallback remained active for 12 minutes.
+```
+
+## Aspect ratio checklist
+
+- `16/9`: medium density, but still cap long vertical stacks.
+- `4/3`: tighter vertical budget. Reduce stacked items first.
+- `16/10`: between `16/9` and `4/3`; apply the same conservative limits when callouts are present.
+
+## Summary
+
+These are authoring constraints, not renderer bugs. When a slide clips:
+
+1. Reduce vertical item count.
+2. Remove or move callouts.
+3. Split dense content across two slides.

package/dist/_raw/content/reference.md

@@ -16,4 +16,5 @@ Use this section when you want quick definitions, mental models, and “what doe
 - [Environment Variables](content/reference/environment-variables.html) — what they are and how to set them
 - [Key Concepts](content/reference/key-concepts.html) — `docroot`, `dist/`, “bundle vs build”, and more
 - [Design Catalog](content/reference/design-catalog.html) — shapes and deterministic infographic figures
+- [Slides Authoring Guidelines](content/reference/slides-authoring-guidelines.html) — practical do/don't rules for density and visual layout
 - [Glossary](content/reference/glossary.html) — quick definitions