kitfly 0.1.2 → 0.2.0

package/dist/_raw/content/deployment/recipes/fly-io.md

@@ -0,0 +1,57 @@
+---
+title: "Recipe: Fly.io"
+description: "Host your built site as a tiny app (Docker-based)"
+last_updated: "2026-02-12"
+---
+
+# Recipe: Fly.io
+
+Fly.io is best when you want your Kitfly site hosted like an "app" (for example: private/internal access, custom headers, or a future path to auth).
+
+This recipe assumes you're comfortable with a small amount of Docker.
+
+If all you want is public static hosting with a custom domain, Netlify or GitHub Pages is usually simpler.
+
+## Prerequisites
+
+- Fly.io account
+- `flyctl` installed and authenticated
+
+## Build
+
+```bash
+make build
+```
+
+## Create a tiny static container (nginx)
+
+In your project root, create a `Dockerfile` like this:
+
+```dockerfile
+FROM nginx:alpine
+COPY dist/ /usr/share/nginx/html/
+```
+
+Then:
+
+```bash
+flyctl launch
+flyctl deploy
+```
+
+If `flyctl launch` asks for a port, you typically want `80` for a static nginx container.
+
+## Custom domain (DNS basics)
+
+Typical pattern:
+
+- `docs.example.com` → **CNAME** to the Fly-provided hostname
+
+Fly provisions HTTPS automatically via Let's Encrypt for custom domains.
+
+## Verify + Rollback
+
+- Verify: load the site, click a few pages, hard refresh, confirm HTTPS lock icon
+- Rollback: Fly retains release history — promote a previous release with `flyctl releases` and `flyctl deploy --image <previous-image>`
+
+See: [Preflight and Rollback](../preflight.html)

package/dist/_raw/content/deployment/recipes/github-pages.md

@@ -0,0 +1,112 @@
+---
+title: "Recipe: GitHub Pages"
+description: "Publish `dist/` on GitHub Pages"
+last_updated: "2026-02-12"
+---
+
+# Recipe: GitHub Pages
+
+GitHub Pages is a good choice when your docs already live in GitHub.
+
+There are many ways to do Pages. This recipe focuses on a beginner-friendly approach first, then a more automated path.
+
+If you're new to deployment: start with Option A. It's not "perfect", but it is simple and reliable.
+
+## Prerequisites
+
+- A GitHub repository
+
+## Important: subdirectory paths
+
+GitHub Pages project sites serve at `https://<user>.github.io/<repo-name>/` by default. Kitfly currently assumes root-level hosting, so links may break in subdirectory deployments.
+
+**Recommended fix:** Configure a **custom domain** (e.g., `docs.example.com`) so the site is served at root. Or use a GitHub Pages "user/org" site (`<org>.github.io`) which serves from `/`.
+
+## Build
+
+```bash
+make build
+```
+
+## Option A (simplest): commit the built site
+
+1. Copy `dist/` into a folder GitHub Pages can serve, commonly `docs/`
+2. Commit and push
+3. In GitHub repo settings → Pages:
+   - Source: "Deploy from a branch"
+   - Folder: `docs/` (or whatever you chose)
+
+Notes:
+
+- This is easy, but it means build artifacts live in git.
+
+## Option B (recommended): build via GitHub Actions
+
+This workflow builds on every push to `main` and publishes `dist/` as the Pages artifact.
+
+```yaml
+# .github/workflows/deploy-pages.yml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install
+
+      - run: make build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+To use this workflow:
+
+1. Go to your repo → Settings → Pages → Source: **GitHub Actions**
+2. Commit the workflow file above
+3. Push to `main`
+
+## Custom domain (DNS basics)
+
+Typical pattern:
+
+- `docs.example.com` → **CNAME** to your `*.github.io` Pages domain
+
+After configuring DNS, add a `CNAME` file inside your `dist/` output (or in a `public/` folder that your build copies to `dist/`) containing your custom domain.
+
+## Verify + Rollback
+
+- Verify: load the site, click a few pages, hard refresh
+- Rollback: redeploy a prior commit (Option A) or re-run a prior workflow (Option B)
+
+See: [Preflight and Rollback](../preflight.html)

package/dist/_raw/content/deployment/recipes/netlify.md

@@ -0,0 +1,99 @@
+---
+title: "Recipe: Netlify"
+description: "Beginner-friendly: upload `dist/` and go"
+last_updated: "2026-02-12"
+---
+
+# Recipe: Netlify
+
+Netlify is a great default for a static Kitfly site because deployment can be as simple as uploading `dist/`.
+
+If you want the "fewest moving parts" setup:
+
+- start with a subdomain like `docs.example.com`
+- deploy the built `dist/` output
+- don't add redirects or fancy build settings until you need them
+
+## Prerequisites
+
+- A Netlify account
+
+## Build
+
+```bash
+make build
+```
+
+## Deploy (simplest: drag-and-drop)
+
+1. Go to Netlify
+2. Create a new site
+3. Drag-and-drop your `dist/` folder
+
+This is perfect for small internal docs, quick demos, and "send a link" situations.
+
+## Deploy (repeatable: connect to Git)
+
+If your docs live in a repo and you want a predictable "push to deploy" workflow:
+
+1. Connect your GitHub/GitLab repo in Netlify
+2. Set build command: `make build`
+3. Set publish directory: `dist`
+
+Netlify will run your build and publish the `dist/` output.
+
+Tip: this is often easier than asking everyone on the team to build locally.
+
+## Configuration file (optional)
+
+For config-as-code, add `netlify.toml` to your project root:
+
+```toml
+[build]
+  command = "make build"
+  publish = "dist"
+
+[build.environment]
+  # Netlify needs Bun installed for the build
+  BUN_VERSION = "1"
+
+[[headers]]
+  for = "/*"
+  [headers.values]
+    X-Frame-Options = "DENY"
+    X-Content-Type-Options = "nosniff"
+```
+
+Note: Netlify doesn't ship Bun by default. You may need to add a build plugin or install step. Check Netlify's docs for current Bun support. Alternatively, build locally and use drag-and-drop or the Netlify CLI:
+
+```bash
+make build
+npx netlify-cli deploy --dir=dist --prod
+```
+
+## Custom domain (DNS basics)
+
+Typical pattern:
+
+- `docs.example.com` → **CNAME** to the Netlify target it gives you
+
+If you need an apex/root domain, follow Netlify's UI guidance for apex handling (it varies by DNS provider).
+
+HTTPS is provisioned automatically via Let's Encrypt once DNS is configured.
+
+## Caching (why you might not see changes)
+
+If you deploy and your browser still shows old content:
+
+- hard refresh (Shift+Reload)
+- try an incognito window
+- wait a minute (some caches take time)
+
+Netlify invalidates its CDN cache on every deploy — if you still see stale content, it's likely browser cache.
+
+## Verify + Rollback
+
+- Verify: load the site, click a few pages, hard refresh, confirm HTTPS lock icon
+- Rollback: re-publish the previous deploy from Netlify's deploy history
+
+See: [Preflight and Rollback](../preflight.html)

package/dist/_raw/content/deployment/recipes/vercel.md

@@ -0,0 +1,88 @@
+---
+title: "Recipe: Vercel"
+description: "Deploy `dist/` to Vercel with CDN and custom domains"
+last_updated: "2026-02-12"
+---
+
+# Recipe: Vercel
+
+Vercel is a good choice when you want fast global CDN, a clean dashboard, and simple "push to deploy" with zero config.
+
+If you're already using Vercel for other projects, this is an easy add.
+
+## Prerequisites
+
+- A Vercel account
+- (For CLI deploys) `vercel` CLI installed: `npm i -g vercel`
+
+## Build
+
+```bash
+make build
+```
+
+Your deployable output is the `dist/` folder.
+
+## Deploy (simplest: drag-and-drop or CLI)
+
+### Option A: CLI deploy (quick)
+
+From your project root:
+
+```bash
+vercel deploy dist/
+```
+
+This uploads `dist/` and gives you a preview URL. To deploy to production:
+
+```bash
+vercel deploy dist/ --prod
+```
+
+### Option B: Connect a Git repo (repeatable)
+
+1. Import your repo in Vercel's dashboard
+2. Set the following in project settings:
+   - **Build Command**: `make build`
+   - **Output Directory**: `dist`
+   - **Install Command**: `bun install`
+
+Now every push to `main` triggers a production deploy. Pull requests get preview deploys automatically.
+
+## Configuration file (optional)
+
+If you prefer config-as-code, add `vercel.json` to your project root:
+
+```json
+{
+  "buildCommand": "make build",
+  "outputDirectory": "dist",
+  "installCommand": "bun install",
+  "framework": null
+}
+```
+
+Setting `"framework": null` tells Vercel not to auto-detect a framework — Kitfly is not a framework Vercel recognizes, so this avoids unexpected behavior.
+
+## Custom domain (DNS basics)
+
+Typical pattern:
+
+- `docs.example.com` → **CNAME** to `cname.vercel-dns.com`
+
+Vercel's dashboard walks you through adding custom domains. HTTPS is provisioned automatically.
+
+## Caching (why you might not see changes)
+
+If you deploy and your browser still shows old content:
+
+- hard refresh (Shift+Reload)
+- try an incognito window
+- Vercel CDN cache usually invalidates on deploy, but DNS propagation can take a few minutes
+
+## Verify + Rollback
+
+- Verify: load the site, click a few pages, hard refresh
+- Rollback: promote a previous deployment from Vercel's dashboard (Deployments → three-dot menu → Promote to Production)
+
+See: [Preflight and Rollback](../preflight.html)

package/dist/_raw/content/deployment/secrets-and-env-vars.md

@@ -0,0 +1,75 @@
+---
+title: "Secrets and Environment Variables"
+description: "How to deploy without leaking credentials"
+last_updated: "2026-02-12"
+---
+
+# Secrets and Environment Variables
+
+Most Kitfly deployments need **no secrets** because the output is static.
+
+You only need secrets when a _deployment tool_ needs credentials (AWS CLI, Netlify CLI, etc.).
+
+## The one rule
+
+Never commit secrets to git.
+
+That includes:
+
+- `.env` files
+- API tokens
+- access keys
+- private keys
+
+If you already committed something sensitive, treat it as leaked:
+
+- rotate/revoke it
+- remove it from git history if needed
+
+## Beginner-friendly pattern
+
+1. Put secret values in environment variables (or your host's secret store).
+2. Keep a local `.env` file _only if you must_ — and make sure it is gitignored.
+3. Use placeholder examples (`.env.example`) to document required variables.
+
+## What is an environment variable?
+
+An environment variable is a named value your terminal (or hosting platform) provides to a command.
+
+If you want a quick primer with copy-paste commands, see:
+
+- [Reference: Environment Variables](../reference/environment-variables.html)
+
+## Host secret stores (recommended)
+
+If your host offers a "Secrets" UI, use it. It's harder to accidentally leak.
+
+Examples (names vary by provider):
+
+- "Environment variables"
+- "Secrets"
+- "Build & deploy settings"
+
+## Least privilege (plain language)
+
+Create credentials that can do only what deployment needs.
+
+Examples:
+
+- An AWS IAM user/policy that can only write to one S3 bucket
+- A Netlify token that can only deploy to one site (if supported)
+- A Cloudflare API token scoped to a single zone or R2 bucket
+
+## Do / Don't
+
+**Do**
+
+- Do keep secrets in a password manager
+- Do rotate tokens periodically
+- Do prefer scoped tokens over "account owner" tokens
+
+**Don't**
+
+- Don't paste secrets into docs
+- Don't put secrets in `site.yaml`
+- Don't share secrets in Slack threads

package/dist/_raw/content/deployment.md

@@ -0,0 +1,128 @@
+---
+title: "Deployment"
+description: "Publish a Kitfly site safely (with beginner-friendly guardrails)"
+last_updated: "2026-02-12"
+---
+
+# Deployment
+
+Kitfly builds a static site. Deployment is just "upload the `dist/` folder".
+
+Before you pick a host, read this once:
+
+## Safety first (please read)
+
+### Do
+
+- Keep secrets out of your repo. Use environment variables or your host's secret store.
+- Use least-privilege credentials (scoped token, minimal permissions).
+- Deploy from a clean build: `make build` (or `bun run build`) and upload `dist/`.
+- Keep a rollback path: retain the previous `dist/` somewhere you can restore quickly.
+- Verify HTTPS works after your first deploy (most hosts provide it free).
+
+### Don't
+
+- Don't commit `.env` files or cloud credentials.
+- Don't "just make the bucket public" unless you understand the blast radius.
+- Don't deploy from a random working tree state you can't reproduce.
+
+Next: read [Secrets and Environment Variables](deployment/secrets-and-env-vars.html) and [Preflight](deployment/preflight.html).
+
+---
+
+## Build vs bundle (two "shipping" modes)
+
+Kitfly has two ways to get your writing out into the world:
+
+- **Host it**: `kitfly build` → upload the `dist/` folder to a static host (the rest of this section).
+- **Send it**: `kitfly bundle` → one HTML file you can email/Slack/upload (offline-friendly).
+
+If you're not sure which you want, start with **bundle** for internal reviews and **build** when you want a permanent link.
+
+## Which host should I pick?
+
+Use this as a quick menu:
+
+### Easiest (beginner-friendly)
+
+- **Cloudflare Pages** — a clean "static site host" with great CDN + custom domains.
+  Recipe: [Cloudflare Pages](deployment/recipes/cloudflare-pages.html)
+
+- **Netlify** — simplest "upload `dist/`" flow, easy custom domains.
+  Recipe: [Netlify](deployment/recipes/netlify.html)
+
+- **GitHub Pages** — great if your docs live in GitHub already.
+  Recipe: [GitHub Pages](deployment/recipes/github-pages.html)
+
+- **Vercel** — fast CDN, clean UI, good "push to deploy" experience.
+  Recipe: [Vercel](deployment/recipes/vercel.html)
+
+### If you're already on a platform
+
+- **AWS S3** — straightforward static hosting; best if your org is already in AWS.
+  Recipe: [AWS S3](deployment/recipes/aws-s3.html)
+
+- **Cloudflare R2** — advanced; object storage that you usually put behind Pages/Workers.
+  Recipe: [Cloudflare R2](deployment/recipes/cloudflare-r2.html)
+
+### "I want an app host"
+
+- **Fly.io** — good when you want a small always-on service (private/internal, auth, etc.).
+  Recipe: [Fly.io](deployment/recipes/fly-io.html)
+
+---
+
+## Base path / subdirectory hosting
+
+Kitfly currently generates sites that assume they are served from the root of a domain (`/`).
+
+If you deploy to a subdirectory path (for example, GitHub Pages project sites serve at `/<repo-name>/`), internal links and asset references may break.
+
+**Workarounds:**
+
+- Use a **custom domain** or **subdomain** (`docs.example.com`) pointed at your host — this avoids the subdirectory issue entirely.
+- For GitHub Pages specifically, use a "user/org" site (`<org>.github.io`) which serves at root, or configure a custom domain.
+
+Base path support is being considered for a future release.
+
+---
+
+## DNS basics (quick primer)
+
+If you bring your own domain, you'll do one of these:
+
+- **Subdomain** (`docs.example.com`) → usually a **CNAME** to your host target.
+- **Apex/root** (`example.com`) → often **A/AAAA** records, or an "ALIAS/ANAME" feature (varies by DNS provider).
+
+Quick definitions:
+
+- **A** = IPv4 address record
+- **AAAA** = IPv6 address record
+- **CNAME** = alias one name to another name
+
+Each recipe calls out the common DNS pattern for that host.
+
+---
+
+## HTTPS
+
+Every host in this section provides free HTTPS (via Let's Encrypt or equivalent). After your first deploy:
+
+- Verify HTTPS works: load `https://your-domain.com` and check the lock icon.
+- If your host offers "force HTTPS" or "redirect HTTP → HTTPS", enable it.
+- Don't serve docs over plain HTTP in production.
+
+---
+
+## Common workflow (host-agnostic)
+
+1. Build: `make build` (outputs `dist/`)
+2. Preview locally (optional): open the built site in a browser
+3. Deploy: upload/sync `dist/`
+4. Verify: load the site, click around, hard refresh
+5. Confirm HTTPS works (first deploy)
+6. Roll back if needed: redeploy the previous `dist/`
+
+If you're not sure what an environment variable is (or how to set one), see:
+
+- [Reference: Environment Variables](reference/environment-variables.html)