kitfly 0.1.2 → 0.2.0

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

@@ -0,0 +1,182 @@
+---
+title: "Approaches"
+description: "Three ways to use kitfly"
+last_updated: "2026-02-03"
+---
+
+# Three Ways to Use Kitfly
+
+Kitfly adapts to how you work. Choose the approach that fits your situation.
+
+## 1. Clone & Customize
+
+**What you get:** The Kitfly engine repo (renderer, template HTML/CSS, example content).
+
+```bash
+git clone https://github.com/3leaps/kitfly my-docs
+cd my-docs
+bun install
+bun run dev
+```
+
+**Directory structure:**
+
+```
+my-docs/
+├── content/          # Replace this with your docs
+│   ├── index.md
+│   └── guide/
+├── src/              # Rendering code (keep this)
+├── scripts/          # Build scripts (keep this)
+├── site.yaml         # Edit to customize
+├── package.json      # Dependencies
+└── ...               # Other template files
+```
+
+**When to use:**
+
+- You want to understand or modify how kitfly works
+- You plan to customize the HTML template or CSS
+- You want version control of the tooling alongside your docs
+- You're comfortable with a bit of extra files in your repo
+
+If you're not changing Kitfly itself, prefer `kitfly init` or pointing Kitfly at a folder.
+
+**Trade-offs:**
+
+- More files to manage
+- Your docs repo includes rendering code
+- Updates require manual merging from upstream
+
+## 2. CLI Init
+
+**What you get:** A clean workspace with minimal structure.
+
+```bash
+# Create new site root
+kitfly init my-handbook
+cd my-handbook
+kitfly dev
+```
+
+**Directory structure:**
+
+```
+my-handbook/
+├── content/
+│   ├── index.md
+│   └── guide/
+│       └── getting-started.md
+├── site.yaml
+└── .gitignore
+```
+
+**When to use:**
+
+- You want a clean start without template clutter
+- You prefer your docs separate from tooling
+- You're starting a new documentation project
+- You want the simplest possible structure
+
+**Trade-offs:**
+
+- Requires kitfly installed (binary or via a JS runtime)
+- Can't customize the rendering without ejecting
+- Depends on kitfly CLI being available
+
+## 3. Point at Folder
+
+**What you get:** Instant rendering of any markdown folder.
+
+```bash
+# Preview existing docs
+kitfly dev ./docs
+
+# Build to static HTML
+kitfly build ./docs --out ./dist
+
+# Custom port
+kitfly dev ./docs --port 4000
+```
+
+**Directory structure:** Whatever you already have.
+
+```
+my-project/
+├── docs/             # kitfly renders this
+│   ├── README.md
+│   ├── api/
+│   └── guides/
+├── src/              # Your project code (ignored)
+└── ...
+```
+
+**When to use:**
+
+- You have existing markdown you want to render
+- You want to preview docs in another repo
+- You're experimenting before committing to a structure
+- You need a quick way to share markdown as HTML
+
+**Trade-offs:**
+
+- No `site.yaml` means less control (auto-discovery only)
+- Need to create `site.yaml` in the folder for customization
+- Requires kitfly installed
+
+## Comparison Table
+
+| Factor           | Clone & Customize | CLI Init     | Point at Folder |
+| ---------------- | ----------------- | ------------ | --------------- |
+| Setup time       | ~1 min            | ~30 sec      | Instant         |
+| Files in repo    | Many              | Few          | None added      |
+| Customization    | Full              | Config only  | Config only     |
+| Requires install | Bun               | Kitfly CLI   | Kitfly CLI      |
+| Updates          | Manual merge      | CLI upgrade  | CLI upgrade     |
+| Best for         | Power users       | New projects | Existing docs   |
+
+## Migrating Between Approaches
+
+### From Clone to Point-at-Folder
+
+If you started with the template but want to separate your docs:
+
+1. Copy your `content/` folder to a new location
+2. Copy `site.yaml` alongside it
+3. Run `kitfly dev ./new-location`
+
+### From Point-at-Folder to A Dedicated Site Root
+
+If you want a clean top-level folder for publishing:
+
+1. Run `kitfly init my-new-site`
+2. Copy your docs into `my-new-site/content/`
+3. Run `kitfly dev my-new-site`
+
+### From Point-at-Folder to Init
+
+If you want more structure:
+
+1. Run `kitfly init my-new-docs`
+2. Copy your markdown into `content/`
+3. Configure `site.yaml`
+
+### From Init to Clone
+
+If you need to customize the rendering:
+
+1. Clone the full template
+2. Copy your `content/` folder over
+3. Preserve your `site.yaml` customizations
+
+## The docroot Concept
+
+Regardless of approach, the `docroot` setting (in `site.yaml`) controls what gets rendered:
+
+```yaml
+docroot: "content"  # Only content/ goes in dist/
+docroot: "docs"     # Only docs/ goes in dist/
+docroot: "."        # Everything in current dir goes in dist/
+```
+
+This is how kitfly separates your documentation from other files in your repo. The machinery (`src/`, `scripts/`, `README.md`, etc.) never appears in your built site unless you explicitly configure it.

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

@@ -0,0 +1,121 @@
+---
+title: "Features"
+description: "What kitfly can do"
+last_updated: "2026-02-03"
+---
+
+# Features
+
+Everything kitfly supports, demonstrated on this page.
+
+## Code Highlighting
+
+Syntax highlighting via Prism.js (loaded from CDN):
+
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+
+console.log(greet("World"));
+```
+
+```python
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+print(greet("World"))
+```
+
+```yaml
+site:
+  title: "My Documentation"
+  theme: "auto"
+```
+
+## Mermaid Diagrams
+
+Flowcharts, sequence diagrams, and more:
+
+```mermaid
+graph LR
+    A[Markdown] --> B[Kitfly]
+    B --> C[HTML]
+    C --> D[Browser]
+```
+
+```mermaid
+sequenceDiagram
+    User->>Kitfly: bun run build
+    Kitfly->>Markdown: Parse files
+    Markdown-->>Kitfly: Content
+    Kitfly->>HTML: Generate pages
+    HTML-->>User: Static site
+```
+
+## Tables
+
+Standard markdown tables with clean styling:
+
+| Feature    | Status | Notes             |
+| ---------- | ------ | ----------------- |
+| Hot reload | ✅     | Instant updates   |
+| Dark mode  | ✅     | System preference |
+| TOC        | ✅     | Auto-generated    |
+| Search     | 🚧     | Coming soon       |
+
+## Text Formatting
+
+Standard markdown formatting:
+
+- **Bold text** for emphasis
+- _Italic text_ for nuance
+- `inline code` for technical terms
+- ~~Strikethrough~~ for corrections
+
+> Blockquotes for callouts and important notes.
+> They can span multiple lines.
+
+## Links
+
+- [Internal link to Getting Started](getting-started.html)
+- [External link to Bun](https://bun.sh)
+- [Reference to Configuration](../reference/configuration.html)
+
+## Lists
+
+Ordered:
+
+1. First item
+2. Second item
+3. Third item
+
+Unordered:
+
+- Item one
+- Item two
+  - Nested item
+  - Another nested
+- Item three
+
+## Images
+
+Standard markdown images are supported across all output modes:
+
+```markdown
+![Alt text](assets/brand/logo.png)
+```
+
+In `kitfly dev` and `kitfly build`, images are served from their original paths. In `kitfly bundle`, images are automatically inlined as base64 data URIs so the single-file HTML works fully offline with no broken references.
+
+## Headings
+
+This page demonstrates h1 through h3. The table of contents on the right is auto-generated from h2 and h3 headings.
+
+### This is an h3
+
+Use h3 for subsections within a topic.
+
+### Another h3
+
+The TOC captures these too.

package/dist/_raw/content/guide/getting-started.md

@@ -0,0 +1,112 @@
+---
+title: "Getting Started"
+description: "Set up your first kitfly site"
+last_updated: "2026-02-03"
+---
+
+# Getting Started
+
+Get your documentation site running in under a minute.
+
+## The Site Root Concept
+
+Kitfly always operates on a folder you point it at (the **site root**).
+
+That folder typically contains:
+
+- `content/` (or `docs/` or any folder you choose)
+- `site.yaml` (recommended) for nav + branding
+- `theme.yaml` (optional) for colors + typography
+
+## Create A New Site Root (Recommended)
+
+```bash
+kitfly init my-docs
+cd my-docs
+kitfly dev
+```
+
+Your browser opens to `http://localhost:3333` with hot reload.
+
+## Add Your Content
+
+1. **Delete the sample content:**
+
+   ```bash
+   rm -rf content/*
+   ```
+
+2. **Add your markdown files:**
+
+   ```bash
+   cp -r ~/my-docs/* content/
+   ```
+
+3. **Organize into sections:**
+
+   ```
+   content/
+   ├── index.md           # Home page
+   ├── guide/             # Becomes "Guide" section
+   │   ├── quickstart.md
+   │   └── tutorial.md
+   └── reference/         # Becomes "Reference" section
+       └── api.md
+   ```
+
+4. **Preview:**
+   ```bash
+   bun run dev
+   ```
+
+Subdirectories automatically become navigation sections. Files within them appear in the sidebar.
+
+## Share It
+
+```bash
+kitfly build --out dist
+
+# Single-file bundle (easiest to email/Slack)
+kitfly bundle --out dist --name my-docs.html
+```
+
+Output goes to `dist/`. You can:
+
+- **Open directly:** `open dist/index.html`
+- **Deploy anywhere:** GitHub Pages, Netlify, S3, any static host
+- **Share as zip:** Compress and email for review
+
+The static HTML works offline - no server required.
+
+## Frontmatter
+
+Add metadata to your markdown files:
+
+```yaml
+---
+title: "Page Title"
+description: "Brief description"
+last_updated: "2026-02-03"
+---
+# Your Content Here
+```
+
+- `title` - Appears in browser tab and header
+- `description` - For meta tags
+- `last_updated` - Shown in page footer
+
+## Next Steps
+
+- [Approaches](approaches.html) - Understand the three ways to use kitfly
+- [Kitfly Overview](kitfly-overview.html) - The big picture and workflows
+- [Features](features.html) - See code highlighting, diagrams, and more
+- [Configuration](../reference/configuration.html) - Customize `site.yaml`
+
+## Running From Source
+
+If you're working on the Kitfly engine itself (this repo), you can run the CLI via Bun:
+
+```bash
+bun install
+bun run src/cli.ts dev .
+```

package/dist/_raw/content/guide/kitfly-overview.md

@@ -0,0 +1,209 @@
+---
+title: "Kitfly Overview"
+description: "What Kitfly is, how it works, and the philosophy behind it"
+last_updated: "2026-02-04"
+---
+
+# Kitfly Overview
+
+Kitfly helps people who aren't web developers turn a folder of writing into something shareable:
+
+- A **single-file HTML bundle** you can email or post in Slack
+- A **static site folder** you can zip and host anywhere
+
+It is intentionally small: one dependency (`marked`) and a codebase you can understand in an afternoon.
+
+## Mission
+
+Many people have documentation that needs to be shared: runbooks, handbooks, project docs, technical guides. The options are often:
+
+- **Too heavy**: Docusaurus, Hugo, Astro require learning build tooling
+- **Too locked**: Notion, Confluence, GitBook require accounts and subscriptions
+- **Too ugly**: Raw markdown or PDFs don't look professional
+
+Kitfly sits in the gap: professional output, minimal complexity, no lock-in.
+
+## What Kitfly Is
+
+- A renderer for markdown folders with a clean, professional default layout
+- A fast way to preview docs locally (`kitfly dev`)
+- A way to ship docs as artifacts (`kitfly bundle`, `kitfly build`)
+- A tool that gives you **your own copy** of the rendering code
+
+## What Kitfly Is Not
+
+Kitfly is not trying to replace full static site generators or app frameworks. These are excellent — use them when you need their power:
+
+| Tool                | Strength                        | Use When                |
+| ------------------- | ------------------------------- | ----------------------- |
+| **Obsidian**        | Personal knowledge, journaling  | You need a second brain |
+| **Docusaurus**      | React ecosystem, versioned docs | You have a dev team     |
+| **Hugo**            | Speed, themes, flexibility      | You want a powerful SSG |
+| **Astro/Starlight** | Modern, component-driven        | You need interactivity  |
+| **VitePress**       | Vue ecosystem, great DX         | You're in the Vue world |
+
+Use Kitfly when you don't need those. Your content is just markdown — migration is straightforward when you outgrow it.
+
+## Three Ways to Use Kitfly
+
+### 1. Create a Standalone Site (Primary Path)
+
+```bash
+kitfly init my-docs
+cd my-docs
+bun install
+bun run dev
+```
+
+This creates a **complete, self-contained site** with:
+
+```
+my-docs/
+├── .kitfly/              # Provenance metadata
+│   └── manifest.json
+├── content/              # Your docs go here
+├── scripts/              # Rendering code (yours now)
+│   ├── dev.ts
+│   ├── build.ts
+│   └── bundle.ts
+├── src/
+│   ├── engine.ts
+│   ├── theme.ts
+│   └── site/
+│       ├── template.html
+│       └── styles.css
+├── schemas/
+├── site.yaml
+├── package.json          # { "dependencies": { "marked": "^15" } }
+└── VERSION               # Provenance: created from kitfly 0.1.0
+```
+
+**The site is detached from kitfly.** You own the code. You can:
+
+- Modify the template, styles, rendering logic
+- Version control the whole thing (`git init`)
+- Never touch kitfly CLI again if you don't want to
+
+**Best for:** New documentation projects, teams who want ownership.
+
+### 2. Point at Existing Docs (Quick Preview)
+
+```bash
+kitfly dev ./my-existing-docs
+kitfly build ./my-existing-docs --out ./dist
+kitfly bundle ./my-existing-docs --name docs.html
+```
+
+Renders any folder of markdown without copying anything into it.
+
+**Best for:** Previewing docs that live in another repo, quick experiments.
+
+### 3. Clone the Kitfly Repo (Contributors)
+
+```bash
+git clone https://github.com/3leaps/kitfly
+cd kitfly
+bun install
+bun run dev
+```
+
+This is the kitfly engine repo. The `content/` folder **is** the kitfly documentation — you're reading it now.
+
+**Best for:** Contributing to kitfly, modifying the CLI, deep customization.
+
+## The "Fly" — How Docs Travel
+
+Kitfly makes docs "fly" by producing artifacts that travel well:
+
+| Command         | Output           | Use Case                   |
+| --------------- | ---------------- | -------------------------- |
+| `kitfly dev`    | Live preview     | Writing and editing        |
+| `kitfly build`  | `dist/` folder   | Deploy to any static host  |
+| `kitfly bundle` | Single HTML file | Email, Slack, shared drive |
+
+The bundle is typically 1-2MB and works offline — open it in any browser.
+
+## Philosophy: Minimalist Site Code
+
+The code that `kitfly init` copies to your project follows strict constraints:
+
+| Metric       | Target | Rationale                      |
+| ------------ | ------ | ------------------------------ |
+| Total lines  | ~500   | Understandable in an afternoon |
+| Dependencies | 1      | No supply chain risk           |
+| Files        | ~10    | Nothing hidden                 |
+
+> **Rule of thumb**: If it can be done with CSS, vanilla JS under 50 lines, or a marked plugin, it belongs. Otherwise, it doesn't.
+
+This is codified in [ADR-0001: Minimalist Site Code](../../docs/decisions/ADR-0001-minimalist-site-code.md).
+
+Users can modify the code — that's expected. But the starting point should be small enough that modification feels safe, not scary.
+
+## Provenance and Updates
+
+When you run `kitfly init`, the site is stamped with provenance:
+
+```json
+// .kitfly/manifest.json
+{
+  "version": "0.1.0",
+  "createdAt": "2026-02-04T12:00:00Z",
+  "files": {
+    "scripts/dev.ts": { "hash": "a1b2c3", "managed": true },
+    ...
+  }
+}
+```
+
+This enables future updates:
+
+```bash
+kitfly update        # Upgrade to latest
+kitfly update 0.2.0  # Upgrade to specific version
+```
+
+The update logic:
+
+1. Read manifest → know current version
+2. For each managed file: check if user modified it (hash comparison)
+3. Safe to replace → update file
+4. User modified → warn, offer merge/skip/force
+5. Update manifest with new version
+
+## This Repo Is the Kitfly Docs
+
+The `content/` folder in this repository is the actual kitfly documentation. When you run `kitfly dev .` here, you're seeing our docs rendered by our tool.
+
+This means:
+
+- **No fake showcase pages** — everything you see is real
+- **Features are demonstrated by use** — Mermaid diagrams, code fences, theming
+- **The docs are always current** — we eat our own cooking
+
+## Architecture Summary
+
+```
+kitfly/                          # The tool
+├── src/cli.ts                   # CLI entry (not copied to users)
+├── src/commands/                # init, update (not copied)
+├── content/                     # Kitfly's own docs (not copied)
+│
+├── scripts/                     # ← Copied to user sites
+│   ├── dev.ts
+│   ├── build.ts
+│   └── bundle.ts
+├── src/site/                    # ← Copied to user sites
+│   ├── template.html
+│   └── styles.css
+├── src/engine.ts                # ← Copied
+├── src/theme.ts                 # ← Copied
+└── schemas/                     # ← Copied
+```
+
+**Kitfly the tool** can grow thoughtfully (more CLI commands, smarter updates). **Site code** stays minimal.
+
+## Next Steps
+
+- [Getting Started](getting-started.md) — Set up your first site
+- [Features](features.md) — See code highlighting, Mermaid diagrams, theming
+- [Configuration](../reference/configuration.md) — Customize `site.yaml` and `theme.yaml`