title: Guide
shell: standard
components:
- type: header
title: Guide
eyebrow: Getting started
subtitle: Install kazam, scaffold a site, run the dev server.
- type: section
eyebrow: Install
heading: Get the binary
components:
- type: markdown
body: |
kazam is a single self-contained Rust binary. No runtime, no Node,
no Python. Pick whichever install method is convenient — all three
land the same binary on your `PATH`.
- type: tabs
tabs:
- label: cargo install (recommended)
components:
- type: markdown
body: |
Works on any system with a Rust toolchain. Installs straight
from GitHub — no crates.io publish needed.
- type: code
language: bash
code: |
cargo install --git https://github.com/tdiderich/kazam
kazam --version
- label: From source
components:
- type: markdown
body: |
For development or if you want to pin to a branch.
- type: code
language: bash
code: |
git clone https://github.com/tdiderich/kazam
cd kazam
cargo build --release
cp target/release/kazam /usr/local/bin/kazam
- label: Prebuilt binary
components:
- type: callout
variant: warn
title: Not yet published
body: "GitHub Releases + `curl | sh` installer and a Homebrew tap are planned. For now, use `cargo install` above."
- type: section
eyebrow: Start
heading: Scaffold a site in 30 seconds
components:
- type: code
language: bash
code: |
kazam init my-site # scaffolds kazam.yaml + index.yaml + AGENTS.md
cd my-site
kazam dev . # watch + serve at localhost:3000, live reload
- type: markdown
body: |
Edit `index.yaml` — the browser reloads on save. Add new `.yaml`
files for new pages. When you're happy, `kazam build . --out dist`
produces a static HTML bundle you can deploy anywhere.
- type: callout
variant: info
title: Ready to ship?
body: "Every kazam build is just plain HTML/CSS/JS. Check the deploy recipes for a copy-paste setup on Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3 + CloudFront, or Firebase."
links:
- label: Deploy recipes
href: deploy.html
variant: primary
- type: section
eyebrow: File structure
heading: What a kazam site looks like
components:
- type: markdown
body: |
Any directory of `.yaml` files. Optional `kazam.yaml` at the root configures
the site name and nav. Every other `.yaml` file becomes a page.
- type: code
language: text
code: |
my-site/
kazam.yaml ← site config (name, 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: Site config
heading: kazam.yaml
components:
- type: markdown
body: |
Shared across every page in the site. `name` is the home-link label in the nav
bar on every page. `nav` links appear in the bar on `shell: standard` pages; their
`href` values are rewritten per-page based on directory depth so they work from
anywhere in the site.
- type: code
language: yaml
code: |
name: My Knowledge Base
theme: dark
nav:
- label: Home
href: index.html
- label: Guide
href: guide.html
- label: API
href: api.html
- type: section
eyebrow: Theming
heading: Colors in one place
components:
- type: markdown
body: |
The renderer exposes a small set of **color tokens** (background,
surface, text, accent, border, semantic green/yellow/red, etc.).
Every component and shell references those tokens via CSS
variables — change a token, every page picks it up on the next
build. No per-component CSS knobs.
There are two built-in themes: `dark` (default) and `light`. Pick
one as the base via the `theme:` key in `kazam.yaml`. If you need
to customize, the `colors:` map overrides individual tokens on top
of the base.
- type: code
language: yaml
code: |
# kazam.yaml
name: My Site
theme: dark
colors:
accent: "#ff9e00" # brand color (link + highlight + buttons)
accent_soft: "rgba(255, 158, 0, 0.08)"
header_border: "rgba(255, 158, 0, 0.2)"
bg: "#0b0b10" # page background
surface: "rgba(255,255,255,0.04)"
- type: markdown
body: |
All available tokens:
- type: definition_list
items:
- term: bg
definition: Page background.
- term: surface
definition: Card/panel backgrounds (low-contrast overlay).
- term: surface_strong
definition: Stronger surface — used for code blocks and kbd pills.
- term: border
definition: Default border color for cards and dividers.
- term: border_strong
definition: Active/hover border (cards on hover, focused table).
- term: accent
definition: The primary brand color. Links, highlights, primary buttons, teal bar on blockquotes and callouts.
- term: accent_soft
definition: Translucent accent background — used for soft tint fills.
- term: text
definition: Primary body text.
- term: text_muted
definition: Secondary text (descriptions, subtitles).
- term: text_subtle
definition: Tertiary text (labels, captions, placeholder-ish).
- term: overlay_hover
definition: Subtle hover highlight for nav links and list rows.
- term: header_border
definition: The teal under-line on the site bar.
- term: green
definition: Semantic success color (tags, badges, status dots).
- term: yellow
definition: Semantic warning color.
- term: red
definition: Semantic danger color.
- type: callout
variant: info
title: Picking a strategy
body: |
Most sites only need to change `accent` and maybe `bg` to feel
custom. If you want a bigger departure, override the whole palette
— or fork `src/theme.rs` and add a new named theme. The goal is
that components stay theme-agnostic either way.
links:
- label: Theme source
href: https://github.com/tdiderich/kazam/blob/main/src/theme.rs
variant: secondary
external: true
- type: section
eyebrow: Navigation
heading: The site bar is built in
components:
- type: markdown
body: |
Every shell renders the same nav bar at the top of the page — you don't opt in,
and there's no per-page wiring. The bar is driven entirely by the site config and
three optional page fields, so navigation stays consistent across `standard`,
`document`, and `deck` pages.
- type: definition_list
items:
- term: site name
definition: Always the left-most item. Links back to `index.html`. Sourced from `name` in `kazam.yaml`.
- term: page.eyebrow
definition: Optional context crumb rendered as `/ EYEBROW` after the site name. Use for the parent section, customer, or category.
- term: page.subtitle
definition: Optional right-side label. Use for dates, versions, or secondary context.
- term: config.nav
definition: Nav links on the right side of `standard` pages. Suppressed on `document` and `deck` so content pages stay focused.
- term: Download PDF
definition: Auto-added on `deck` pages. Print-optimized CSS is built in — decks export edge-to-edge, documents export without the bar.
- type: code
language: yaml
code: |
title: Q3 Business Review
shell: deck
eyebrow: Acme # → "kazam / ACME" in the bar
subtitle: April 2026 # → right-side label
slides:
- label: Cover # set hide_label: true for a title slide with no "COVER" eyebrow
hide_label: true
components:
- type: image
src: /assets/logo.svg
max_width: 96
align: center
- type: header
title: "Q3 Business Review"
align: center
- label: Outcomes
components: [...]
- type: section
eyebrow: Page structure
heading: Every page is a tree
components:
- type: markdown
body: |
A page has a `title`, a `shell`, and an ordered list of `components`. For `deck`
shell, replace `components` with `slides`, where each slide has its own components.
- type: code
language: yaml
code: |
title: Page Title
shell: standard
components:
- type: breadcrumb
items:
- label: Home
href: index.html
- label: Page Title
- 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: Run
heading: Build or watch
components:
- type: tabs
tabs:
- label: Dev
components:
- type: markdown
body: |
Serves at `localhost:3000`, watches every `.yaml` file, rebuilds
on change, live-reloads the browser.
- type: code
language: bash
code: kazam dev ./my-site --port 3000
- label: Build
components:
- type: markdown
body: One-shot build to an output directory.
- type: code
language: bash
code: kazam build ./my-site --out ./dist
- type: callout
variant: info
title: Next up
body: Every page is composed from ~20 typed components — card grids, tables, tabs, callouts, decks. See them all.
links:
- label: Components reference
href: components/index.html
variant: primary
- label: See use cases
href: about.html
variant: secondary