title: Full Tour
shell: standard

components:
  - type: header
    title: Full Tour
    eyebrow: 3 minutes
    subtitle: How a kazam site is shaped — file tree, shells, components, kazam.yaml. Everything you need to start writing 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`. That's it. 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: 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: Your first real page
    heading: Three starting points
    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: 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.
    links:
      - label: Components reference
        href: components/index.html
        variant: primary
      - label: Pick a theme
        href: themes.html
        variant: secondary
      - label: Deploy recipes
        href: deploy.html
        variant: secondary
