kitfly 0.2.1 → 0.2.4

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: