Kairo Docs

Appearance

Documentation ​

This docs site is a static VitePress site that lives entirely inside docs-site/ in the main Kairo repo — it is not a separate project.

Where pages live ​

docs-site/
  index.md                 landing page
  orientation.md
  future-features.md
  release.md
  features/
    today.md, calendar.md, week.md, inbox-projects.md,
    quick-add.md, settings-updates.md, desktop-tauri.md
  editing/
    styling.md, features.md, documentation.md   (this page)
  .vitepress/
    config.ts               nav + sidebar structure, site title/description

Every page is plain Markdown with VitePress extensions available (containers, code-block line highlighting, etc. — see the VitePress docs if you need them, but plain Markdown is fine for most edits).

Live preview while editing ​

bash
npm run docs:dev

This starts a local VitePress dev server (hot-reloading) — open the printed localhost URL, edit any .md file, and see it update instantly.

Adding or renaming a page ​

  1. Create/edit the .md file under docs-site/.
  2. If it's a new page (not just an edit to an existing one), add it to the nav and/or sidebar in docs-site/.vitepress/config.ts so it's actually reachable — VitePress doesn't auto-discover pages into the sidebar.
  3. Preview with npm run docs:dev to confirm the link resolves and the page renders as expected.

Building and shipping ​

bash
npm run docs:build      # builds the static site to docs-site/.vitepress/dist
npm run docs:preview    # serves that build locally, to sanity-check before pushing

Deployment is automatic: pushing to main triggers a Cloudflare Pages build + deploy of docs-site/ — no manual deploy step. Just commit and push.

For the full run/deploy walkthrough — including running locally with the AI chat (needs wrangler, not docs:dev) and first-time Cloudflare setup — see Running & Deploying. To restrict the live site to your GitHub account, see Access Control.

The AI chat widget ​

The site's chat assistant is a small Cloudflare Pages Function proxying Gemini, at functions/api/chat.ts (repo root, sibling to docs-site/). It needs a GEMINI_API_KEY secret set in the Cloudflare Pages project (never committed) — if chat stops responding after a deploy, confirm that secret is still set before debugging the function. To test chat locally, see Running & Deploying.

Quick checklist for a docs change ​

  • [ ] Edited the right .md file (content only — leave .vitepress/ and index.md alone unless you're intentionally changing nav/landing)
  • [ ] New page added to config.ts nav/sidebar if applicable
  • [ ] npm run docs:build succeeds locally
  • [ ] Internal links ([text](/path)) resolve — VitePress build fails loudly on a dead internal link