title: Authoring Guide
shell: standard
components:
- type: header
title: Authoring Guide
eyebrow: 5 minutes
subtitle: How a kazam site is shaped - file tree, shells, components, freshness metadata, kazam.yaml. Everything you need to write real pages.
- type: section
eyebrow: Anatomy
heading: A kazam site is a folder of YAML
components:
- type: markdown
body: |
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.
- type: code
language: text
code: |
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
- type: section
eyebrow: Pages
heading: title + shell + components
components:
- type: markdown
body: |
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.
- type: code
language: yaml
code: |
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.
- type: section
eyebrow: Freshness
heading: Declare ownership and review cadence
components:
- type: markdown
body: |
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.
- type: code
language: yaml
code: |
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:
...
- type: markdown
body: |
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.
- type: callout
variant: info
title: Full freshness reference
body: Banner variants, build report format, status computation, and the agent workflow pattern.
links:
- label: Freshness guide →
href: freshness.html
variant: secondary
- type: section
eyebrow: Shells
heading: Three ways a page can be chromed
components:
- type: markdown
body: |
The `shell` decides the top-level layout. Every shell gets the same
built-in site bar - you're picking how the content area behaves.
- type: tabs
tabs:
- label: standard
components:
- type: markdown
body: |
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.
- type: code
language: yaml
code: |
title: API reference
shell: standard
components:
- type: header
title: API
- type: markdown
body: |
The full endpoint list.
- label: document
components:
- type: markdown
body: |
A centered card optimized for printing. No nav links,
print-friendly CSS baked in. Good for briefs, agendas,
one-pagers, pre-reads.
- type: code
language: yaml
code: |
title: Q3 incident brief
shell: document
components:
- type: header
title: Incident Brief
- type: markdown
body: |
Summary, timeline, impact…
- label: deck
components:
- type: markdown
body: |
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.
- type: code
language: yaml
code: |
title: Q3 Business Review
shell: deck
slides:
- label: Cover
hide_label: true
components:
- type: header
title: Q3 Business Review
align: center
- label: Outcomes
components: [...]
- type: section
eyebrow: Site config
heading: kazam.yaml in full
components:
- type: markdown
body: |
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.
- type: code
language: yaml
code: |
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"
- type: callout
variant: info
title: Full token list
body: The themes page shows every stock palette as a swatch and lists every overridable color token.
links:
- label: Themes reference →
href: themes.html
variant: secondary
- type: section
eyebrow: Starting points
heading: Three page shapes
components:
- type: markdown
body: |
Copy one of these into a new `.yaml` file and start editing. The
`dev` server reloads on save - tweak, see the result, repeat.
- type: tabs
tabs:
- label: Minimal
components:
- type: markdown
body: |
Header, markdown, and a callout. A good shape for a docs
index or a landing.
- type: code
language: yaml
code: |
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.
- label: With data
components:
- type: markdown
body: |
Header + stat grid + table. The shape most business pages
want - a QBR summary, a weekly report, a service catalog.
- type: code
language: yaml
code: |
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 }
- label: Print-ready doc
components:
- type: markdown
body: |
`shell: document` swaps in a centered, print-optimized card.
Same components. Good for briefs, agendas, and one-pagers
you'll export to PDF.
- type: code
language: yaml
code: |
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.
- type: callout
variant: info
title: Next up
body: 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.
links:
- label: Components reference
href: components/index.html
variant: primary
- label: Freshness
href: freshness.html
variant: secondary
- label: Deploy
href: deploy.html
variant: secondary