kitfly 0.1.2 → 0.2.0

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

@@ -0,0 +1,259 @@
+---
+title: "Configuration"
+description: "Customize your kitfly site"
+last_updated: "2026-02-03"
+---
+
+# Configuration
+
+Kitfly uses `site.yaml` for configuration. Everything is optional - sensible defaults apply.
+
+## Quick Reference
+
+```yaml
+# yaml-language-server: $schema=./schemas/v0/site.schema.json
+schemaVersion: "0.1.0"
+docroot: "content"
+title: "My Documentation"
+version: "2.4.1"
+home: "index.md"
+
+brand:
+  name: "My Project"
+  url: "https://myproject.com"
+  external: true
+
+sections:
+  - name: "Guide"
+    path: "guide"
+  - name: "API"
+    path: "api"
+
+footer:
+  copyright: "© 2026 My Project. All rights reserved."
+  links:
+    - text: "Privacy"
+      url: "/privacy"
+    - text: "Terms"
+      url: "/terms"
+  attribution: true
+```
+
+## Settings
+
+### docroot
+
+**The most important setting.** Controls what folder contains your documentation.
+
+```yaml
+docroot: "content"
+```
+
+| Value       | Meaning                                    |
+| ----------- | ------------------------------------------ |
+| `"content"` | Markdown lives in `content/` (recommended) |
+| `"docs"`    | Markdown lives in `docs/`                  |
+| `"."`       | Markdown lives in repo root                |
+
+**Why it matters:** Only files under `docroot` appear in your built site. Everything else - `src/`, `scripts/`, `README.md`, `package.json` - stays out of `dist/`.
+
+See [Folder Structure](structure.html) for details.
+
+### title
+
+Site title. Appears in browser tab and header.
+
+```yaml
+title: "My Documentation"
+```
+
+### version
+
+Site/content version shown in the footer provenance zone.
+
+```yaml
+version: "2.4.1"
+```
+
+Version resolution order:
+
+1. `site.yaml` `version`
+2. Git tag on `HEAD` (exact match, `v` prefix removed)
+3. Omitted from footer provenance if neither is available
+
+### home
+
+Home page file (relative to docroot). Becomes `index.html`.
+
+```yaml
+home: "index.md"
+```
+
+If omitted, the first file from the first section is used.
+
+### brand
+
+Header branding:
+
+```yaml
+brand:
+  name: "My Project" # Text in header
+  url: "/" # Logo link
+  logo: "assets/brand/my-logo.png" # Sidebar logo image
+  favicon: "assets/brand/favicon-32.png" # Browser tab icon
+  external: true # Open in new tab (optional)
+```
+
+The logo renders inside a bounded slot that preserves aspect ratio:
+
+| Breakpoint       | Max Height | Max Width |
+| ---------------- | ---------- | --------- |
+| Desktop          | 64px       | 180px     |
+| Tablet (≤1024px) | 56px       | 150px     |
+| Mobile (≤768px)  | 48px       | 130px     |
+
+Both square marks and wide wordmarks fit cleanly. SVG and PNG formats are supported. For SVGs, ensure the `viewBox` is tightly cropped to the artwork — an oversized canvas will render the logo too small.
+
+### sections
+
+Navigation structure. Each section becomes a sidebar group.
+
+```yaml
+sections:
+  - name: "Guide" # Display name
+    path: "guide" # Directory (relative to docroot)
+  - name: "Reference"
+    path: "reference"
+```
+
+**Auto-discovery:** If `files` is omitted, all `.md` files in the directory are included, recursively up to `maxDepth` levels deep.
+
+```yaml
+sections:
+  - name: "Reference"
+    path: "reference"
+    maxDepth: 6 # Discover up to 6 levels deep (default: 4, max: 10)
+```
+
+| Setting    | Default | Range | Effect                                            |
+| ---------- | ------- | ----- | ------------------------------------------------- |
+| `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.
+
+**Explicit files:** For precise control over which files appear (bypasses auto-discovery):
+
+```yaml
+sections:
+  - name: "Overview"
+    path: "."
+    files: ["README.md", "CHANGELOG.md"]
+```
+
+### 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.
+
+```
+v0.1.1 · Published 2026-02-10     © 2026 Acme Inc. · acme.com     Built with Kitfly
+← provenance (automatic)          ← copyright + links (configurable) → ← attribution →
+```
+
+| Field          | Default                          | What it controls                          |
+| -------------- | -------------------------------- | ----------------------------------------- |
+| `copyright`    | `© {publish-year} {brand.name}`  | The copyright text in the center zone     |
+| `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          |
+
+**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:
+
+```yaml
+# brand.name is "Acme Productbook" — that's the product title
+# but the copyright holder is the company
+footer:
+  copyright: "© 2026 Acme, Inc."
+```
+
+This changes only the copyright. The brand URL link and attribution are unaffected.
+
+**Make the copyright clickable:**
+
+```yaml
+footer:
+  copyright: "© 2026 3 Leaps, LLC"
+  copyrightUrl: "https://3leaps.net"
+```
+
+When `copyrightUrl` is set, the copyright text becomes a link. When omitted, it renders as plain text.
+
+**Full example with all options:**
+
+```yaml
+footer:
+  copyright: "© 2026 My Company, Inc."
+  copyrightUrl: "https://mycompany.com"
+  links:
+    - text: "Privacy"
+      url: "/privacy"
+    - text: "Terms"
+      url: "/terms"
+  attribution: true
+```
+
+When `links` is set, it replaces the default brand URL link. When `links` is omitted, your `brand.url` appears as a link (with the protocol stripped — `https://acme.com` displays as `acme.com`).
+
+Set `footer.attribution: false` to remove the "Built with Kitfly" text from the footer entirely.
+
+### theme layout (`theme.yaml`)
+
+`theme.yaml` can override layout variables, including sidebar width.
+
+```yaml
+# theme.yaml
+layout:
+  sidebarWidth: "320px"
+```
+
+This sets `--sidebar-width` and applies to dev server, static builds, and bundles.
+
+Recommended range: `240px` to `400px` depending on logo and nav label length.
+
+## Frontmatter
+
+Each markdown file can have YAML frontmatter:
+
+```yaml
+---
+title: "Page Title"
+description: "Brief description for meta tags"
+last_updated: "2026-02-03"
+---
+# Content starts here
+```
+
+| Field          | Purpose                         |
+| -------------- | ------------------------------- |
+| `title`        | Page title (overrides filename) |
+| `description`  | Meta description                |
+| `last_updated` | Shown in page footer            |
+
+## No Configuration
+
+If you don't create `site.yaml`, kitfly will:
+
+1. Look for `content/` directory
+2. Auto-discover sections from subdirectories
+3. Use default title ("Documentation") and branding
+
+This means you can start with just markdown files and add `site.yaml` later.
+
+## Schema Validation
+
+For editor autocomplete and validation, reference the schema:
+
+```yaml
+# yaml-language-server: $schema=./schemas/v0/site.schema.json
+```
+
+The schema is in `schemas/v0/site.schema.json`.

package/dist/_raw/content/reference/design-catalog.md

@@ -0,0 +1,167 @@
+---
+title: "Design Catalog (Shapes and Figures)"
+description: "Deterministic layout building blocks for slides (and when to use diagram engines instead)"
+last_updated: "2026-02-12"
+---
+
+# Design Catalog (Shapes and Figures)
+
+Kitfly is **not** trying to recreate diagram engines like Mermaid or PlantUML.
+
+Those tools compute layout from relationships (a graph). That’s powerful, but the output can be hard to predict and hard for AI agents to control precisely.
+
+Kitfly’s approach is simpler: a small catalog of **deterministic** building blocks that render predictably inside a slide.
+
+## The two layers
+
+### Shapes (primitives)
+
+**Shapes** are atomic building blocks with **no internal layout logic**.
+
+They are the “ink” you can draw with:
+
+- boxes, circles, diamonds
+- arrows and connectors
+- badges, labels, callouts
+
+You (or an agent) decide where they go.
+
+### Figures (deterministic infographic patterns)
+
+**Figures** are composed patterns built from shapes.
+
+A figure has a known structure (a fixed topology) and a deterministic layout algorithm, such as CSS Grid or flexbox. You fill named **slots**, and the figure handles spacing and alignment inside its bounding box.
+
+Examples of figures we expect to support:
+
+- timeline
+- layer cake
+- quadrant grid
+- hub-and-spoke
+- funnel
+- cycle wheel
+
+## The boundary rule (simple)
+
+If you can enumerate the elements and assign them positions (or slots) at authoring time, it belongs in the **shapes/figures** system.
+
+If element positions must be computed from relationships between a variable set of nodes, it belongs in a **diagram engine**.
+
+## Why this helps (especially for AI)
+
+- **Predictable output**: “Put this in column 2” is easier than “hope the layout engine does what I meant”.
+- **Slide-quality control**: common business infographics need alignment more than graph theory.
+- **Minimal surface area**: a catalog is easier to learn and easier to audit than a full diagram framework.
+
+## Where this is going
+
+This page is the entry point. During the v0.2.x cycle, we’ll extend it with:
+
+- a fuller shape list (what exists, what each is for)
+- a figure list (patterns, slot definitions, examples)
+- guidance on when to choose figures vs Mermaid (and when not to)
+
+## What ships now (current)
+
+Current core support focuses on **shapes** as `.block` modifiers:
+
+- `circle`
+- `pill`
+- `diamond`
+- `chevron`
+- `hexagon`
+- `triangle`
+- `block-arrow`
+
+For simple directional storytelling, use `block-flow` with directional shapes.  
+General connector routing remains deferred to plugin/engine phases.
+
+## How to use this (today)
+
+These examples use plain HTML inside Markdown. That’s intentional: it’s simple, deterministic, and easy for both AI agents and frontend authors to write and review.
+
+You can use these classes in slides mode (recommended) and in docs mode when you want a diagram-like block in the middle of a page.
+
+## Live Examples
+
+Use the theme toggle in the header to switch light/dark and see the same examples adapt automatically.
+
+### Shape gallery (atomic primitives)
+
+<div class="block-grid cols-4">
+  <div class="block">box</div>
+  <div class="block circle accent">1</div>
+  <div class="block pill accent">pill</div>
+  <div class="block diamond">diamond</div>
+  <div class="block chevron">chevron</div>
+  <div class="block hexagon">hex</div>
+  <div class="block triangle">tri</div>
+  <div class="block block-arrow accent">arrow</div>
+</div>
+
+```html
+<div class="block-grid cols-4">
+  <div class="block">box</div>
+  <div class="block circle accent">1</div>
+  <div class="block pill accent">pill</div>
+  <div class="block diamond">diamond</div>
+  <div class="block chevron">chevron</div>
+  <div class="block hexagon">hex</div>
+  <div class="block triangle">tri</div>
+  <div class="block block-arrow accent">arrow</div>
+</div>
+```
+
+### Directional flow (no connector engine)
+
+<div class="block-flow">
+  <div class="block chevron">Intake</div>
+  <div class="block block-arrow accent">Assess</div>
+  <div class="block chevron">Plan</div>
+  <div class="block block-arrow accent">Ship</div>
+</div>
+
+```html
+<div class="block-flow">
+  <div class="block chevron">Intake</div>
+  <div class="block block-arrow accent">Assess</div>
+  <div class="block chevron">Plan</div>
+  <div class="block block-arrow accent">Ship</div>
+</div>
+```
+
+### Modifier comparison (same base shape, side-by-side)
+
+<div class="block-grid cols-4">
+  <div class="block">default</div>
+  <div class="block accent">accent</div>
+  <div class="block outline">outline</div>
+  <div class="block muted">muted</div>
+</div>
+
+```html
+<div class="block-grid cols-4">
+  <div class="block">default</div>
+  <div class="block accent">accent</div>
+  <div class="block outline">outline</div>
+  <div class="block muted">muted</div>
+</div>
+```
+
+### Modifier comparison on one shape (circle)
+
+<div class="block-grid cols-4">
+  <div class="block circle">A</div>
+  <div class="block circle accent">A</div>
+  <div class="block circle outline">A</div>
+  <div class="block circle muted">A</div>
+</div>
+
+```html
+<div class="block-grid cols-4">
+  <div class="block circle">A</div>
+  <div class="block circle accent">A</div>
+  <div class="block circle outline">A</div>
+  <div class="block circle muted">A</div>
+</div>
+```

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

@@ -0,0 +1,66 @@
+---
+title: "Environment Variables"
+description: "A beginner-friendly primer (with copy-paste examples)"
+last_updated: "2026-02-12"
+---
+
+# Environment Variables
+
+An environment variable is a named value your terminal (or hosting platform) provides to a command.
+
+Examples:
+
+- `PORT=3333`
+- `AWS_PROFILE=my-team`
+- `NETLIFY_AUTH_TOKEN=...`
+
+## Why they matter for deployment
+
+Kitfly’s output is static. Deployment tools often need credentials, and environment variables are a common way to provide them without putting secrets in files.
+
+Important: don’t commit secrets to git. See:
+
+- [Deployment: Secrets and Environment Variables](../deployment/secrets-and-env-vars.html)
+
+## How to set an environment variable
+
+### macOS / Linux (bash, zsh)
+
+Set for a single command:
+
+```bash
+MY_VAR="hello" my-command
+```
+
+Set for your current terminal session:
+
+```bash
+export MY_VAR="hello"
+my-command
+```
+
+### Windows (PowerShell)
+
+Set for your current session:
+
+```powershell
+$env:MY_VAR = "hello"
+my-command
+```
+
+## `.env` files (optional)
+
+Some tools can read a `.env` file.
+
+If you use one:
+
+- keep it local-only
+- make sure it is gitignored
+- consider adding a `.env.example` with placeholder values (safe to commit)
+
+## Quick troubleshooting
+
+- If a command says a variable is missing, print it:
+  - macOS/Linux: `echo "$MY_VAR"`
+  - PowerShell: `echo $env:MY_VAR`
+- If it prints empty, it’s not set in that shell session.

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

@@ -0,0 +1,92 @@
+---
+title: "Glossary"
+description: "Quick definitions for common Kitfly terms"
+last_updated: "2026-02-12"
+---
+
+# Glossary
+
+If you’re new to static sites or developer tooling, this page is for you. It’s okay to not know this stuff yet.
+
+## Site root
+
+The folder you run Kitfly commands from. It typically contains `site.yaml` and your `docroot` folder.
+
+## `docroot`
+
+The folder Kitfly reads as your documentation source (often `content/`).
+
+## Section
+
+A left-nav grouping in Kitfly. In `site.yaml`, each `sections:` entry becomes a navigation section.
+
+## `dist/`
+
+The output folder created by `kitfly build` (the folder you deploy).
+
+## Build
+
+The `kitfly build` output: a folder of files (`dist/`) intended for hosting on a static site provider.
+
+## Bundle
+
+The `kitfly bundle` output: a single HTML file intended for sending (email/Slack/upload) and offline viewing.
+
+## Dev server
+
+The local server started by `kitfly dev` for authoring and previewing your docs with hot reload.
+
+## Hot reload
+
+When the page refreshes automatically after you edit a file. Kitfly watches your docs and config while the dev server is running.
+
+## Frontmatter
+
+Optional YAML metadata at the top of a Markdown file (between `---` lines). Common fields include `title` and `description`.
+
+## Mode
+
+Kitfly site layout mode.
+
+- `docs` (default): scrolling pages optimized for reading
+- `slides` (v0.2.0+): fixed-aspect slides with keyboard navigation
+
+## Aspect ratio
+
+Slides-only setting that controls the shape of the slide frame (for example `16/9` or `4/3`).
+
+## Static hosting
+
+Hosting that serves files (HTML/CSS/JS/images) without running your own backend server.
+
+## Theme
+
+A set of styling choices for your site (colors, typography, layout details), typically configured in `theme.yaml`.
+
+## Template
+
+An optional starting point you can generate with `kitfly init --template ...`. Templates are just folders of Markdown and config you own and can edit.
+
+## Mermaid
+
+A diagram syntax that Kitfly can render in the browser (via CDN) for flowcharts, sequence diagrams, and more.
+
+## Prism
+
+The syntax highlighter Kitfly uses for code blocks (via CDN).
+
+## CDN
+
+Content Delivery Network. A fast way to load shared libraries (like Mermaid/Prism) without bundling them into Kitfly.
+
+## SRI / integrity hash
+
+“Subresource Integrity” hashes help browsers verify a CDN file hasn’t been tampered with. You’ll see these as `integrity="sha384-..."` in some setups.
+
+## Environment variable
+
+A named value provided to commands and apps by your shell or host platform (often used for secrets).
+
+## 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.

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

@@ -0,0 +1,118 @@
+---
+title: "Key Concepts"
+description: "Mental models for how Kitfly works"
+last_updated: "2026-02-12"
+---
+
+# Key Concepts
+
+Kitfly is intentionally small. If you understand these concepts, you understand the whole tool.
+
+## Site root
+
+Your “site root” is the folder you run commands from. It usually contains:
+
+- `site.yaml`
+- `content/` (your docs)
+
+When you run `kitfly dev`, `kitfly build`, or `kitfly bundle`, you usually run them from your site root.
+
+## `docroot`
+
+`docroot` is the folder Kitfly renders into a site.
+
+In most projects:
+
+- `docroot: "content"`
+
+Think of `docroot` as “the folder I’m publishing”.
+
+## Sections
+
+Sections are what you see in the left navigation. Each section maps to a folder.
+
+In `site.yaml`, it looks like:
+
+```yaml
+sections:
+  - name: "Guide"
+    path: "guide"
+```
+
+If you point `kitfly` at a folder without a `site.yaml`, Kitfly can auto-discover sections from subfolders (handy for quick previews).
+
+## `dist/` (build output)
+
+`kitfly build` produces a static site folder, commonly:
+
+- `dist/`
+
+You deploy by uploading/syncing `dist/` to a static host.
+
+## Build vs Bundle vs Dev
+
+- **Dev** (`kitfly dev`) is for writing: it runs a local server and reloads when files change.
+- **Build** (`kitfly build`) is for hosting: it creates a `dist/` folder you can upload.
+- **Bundle** (`kitfly bundle`) is for sending: it creates a single HTML file you can email or drop in Slack.
+
+## Build vs Bundle
+
+- **Build**: outputs a folder (`dist/`) with multiple files (HTML + assets).
+- **Bundle**: outputs a single HTML file you can email or upload (offline-friendly).
+
+## Markdown + frontmatter
+
+Kitfly renders Markdown files (`.md`). You can optionally add YAML frontmatter at the top of a file:
+
+```yaml
+---
+title: "My Page"
+description: "What this page is about"
+---
+```
+
+Frontmatter is the easiest way to control titles and add metadata without changing your headings.
+
+## Theme (`theme.yaml`)
+
+Kitfly themes control the look of your site (colors, typography, layout details). The defaults are meant to be clean and readable.
+
+If you don’t want to think about design: don’t touch it.
+
+If you do: `theme.yaml` is your main “make it mine” knob.
+
+## Modes: docs vs slides (v0.2.0+)
+
+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 mode is configured in `site.yaml`:
+
+```yaml
+mode: slides
+aspect: "16/9"
+```
+
+## 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.
+
+## Provenance
+
+Kitfly can emit provenance information (version/build date/git info) so you can answer “what did we ship?”.
+
+If you see “unversioned”, it usually means your site didn’t set a `version` in `site.yaml` and the current git commit isn’t exactly tagged.
+
+## “Static site” (plain language)
+
+A static site is just files. No server-side database, no login, no runtime code required.
+
+That’s why Kitfly sites are easy to:
+
+- host almost anywhere
+- email as an attachment (bundle)
+- keep offline