Full Tour
How a kazam site is shaped — file tree, shells, components, kazam.yaml. Everything you need to start writing real pages.
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. That's it. 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.
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 starting points
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.
You've seen the shape. The components reference has every primitive you can drop into a page; the themes page covers palettes; deploy covers shipping.