A kazam site is a folder of YAML
Every .yaml file becomes a page. Subdirectories become URL paths. One optional kazam.yaml at the root holds site-wide config (name, theme, nav). That's the whole model.
my-site/
kazam.yaml ← site config (name, theme, nav)
index.yaml ← home page → _site/index.html
guide.yaml ← → _site/guide.html
reference/
api.yaml ← → _site/reference/api.html
cli.yaml ← → _site/reference/cli.html
title + shell + components
Every page is three things: a title, a shell, and an ordered list of components. No routing config, no layout hierarchy, no templates to register.
title: Page Title
shell: standard
components:
- type: header
title: Page Title
- type: markdown
body: |
Any **markdown** here. Tables, code, lists, blockquotes.
- type: callout
variant: success
title: Done
body: This page is ready.
Declare ownership and review cadence
Any page can carry a freshness: block. Add it when the page has a real owner and should be reviewed on a schedule. kazam uses it at build time — no runtime, no network calls.
title: Onboarding Guide
shell: standard
freshness:
updated: 2026-05-01 # ISO date of the last content change
review_every: 90d # Nd | Nw | Nm | Ny | weekly | monthly | quarterly | yearly
owner: hr@example.com # free-form — email, Slack handle, team name
sources_of_truth: # bare URL or { label, href }
- label: Notion — HR onboarding doc
href: https://notion.so/your-page
- label: "#onboarding"
href: https://company.slack.com/archives/C012345
components:
...
Build output: a yellow banner if review is due within 7 days, a red banner if overdue. _site/stale.md lists every stale page — hand it to your agent to prioritize what to refresh.
Banner variants, build report format, status computation, and the agent workflow pattern.
Three ways a page can be chromed
The shell decides the top-level layout. Every shell gets the same built-in site bar — you're picking how the content area behaves.
The default. Nav links on the right of the bar, flowing content below. Docs, guides, landing pages, references — anything you'd reach for a docs site for.
title: API reference
shell: standard
components:
- type: header
title: API
- type: markdown
body: |
The full endpoint list.
A centered card optimized for printing. No nav links, print-friendly CSS baked in. Good for briefs, agendas, one-pagers, pre-reads.
title: Q3 incident brief
shell: document
components:
- type: header
title: Incident Brief
- type: markdown
body: |
Summary, timeline, impact…
Full-viewport slides with keyboard nav and PDF export. components: becomes slides:, each with its own component list. Good for QBRs, strategy reviews, pitch decks.
title: Q3 Business Review
shell: deck
slides:
- label: Cover
hide_label: true
components:
- type: header
title: Q3 Business Review
align: center
- label: Outcomes
components: [...]
kazam.yaml in full
One optional file at the root. name is the home-link label in the site bar. nav links get their href values rewritten per-page based on directory depth, so they work from anywhere in the site. theme picks a stock palette; colors: overrides individual tokens on top.
name: My Knowledge Base
theme: dark # dark | light | red/orange/yellow/green/blue/indigo/violet
texture: dots # optional — decorative background
glow: accent # optional — soft accent wash
description: My knowledge base. # meta description
url: https://example.com # absolute URL for og:image / canonical
nav:
- label: Home
href: index.html
- label: Guide
href: guide.html
- label: Reference
href: reference/api.html
children: # optional dropdown
- label: API
href: reference/api.html
- label: CLI
href: reference/cli.html
colors: # optional — override any token
accent: "#ff9e00"
bg: "#0b0b10"
The themes page shows every stock palette as a swatch and lists every overridable color token.
Three page shapes
Copy one of these into a new .yaml file and start editing. The dev server reloads on save — tweak, see the result, repeat.
Header, markdown, and a callout. A good shape for a docs index or a landing.
title: My first page
shell: standard
components:
- type: header
title: My first page
subtitle: Built with kazam.
- type: markdown
body: |
A paragraph here. Add `**markdown**`, lists, tables,
whatever — it all renders.
- type: callout
variant: success
title: You're up
body: Save the file and the browser reloads.
Header + stat grid + table. The shape most business pages want — a QBR summary, a weekly report, a service catalog.
title: Q3 Pipeline
shell: standard
components:
- type: header
title: Q3 Pipeline
subtitle: Three active opportunities.
- type: stat_grid
columns: 3
stats:
- label: Total ACV
value: $1.2M
color: green
- label: Weighted
value: $480K
- label: At risk
value: $200K
color: yellow
- type: table
columns:
- key: account
label: Account
- key: stage
label: Stage
- key: acv
label: ACV
rows:
- { account: Acme, stage: Contract, acv: $600K }
- { account: Globex, stage: POC, acv: $400K }
- { account: Initech, stage: Discovery, acv: $200K }
shell: document swaps in a centered, print-optimized card. Same components. Good for briefs, agendas, and one-pagers you'll export to PDF.
title: Incident brief — 2026-04-19
shell: document
components:
- type: header
title: Incident Brief
subtitle: Payments outage — 2026-04-19
- type: markdown
body: |
## Summary
Payments returned 500s for ~18 minutes.
## Timeline
- **14:02** — first alert
- **14:05** — rollback started
- **14:20** — all green
## Impact
~340 failed transactions, all retried successfully.
The components reference has every primitive you can drop into a page. Freshness covers build-time staleness tracking. Themes covers palettes and deploy covers shipping.