Getting Started

Working docs

This site is meant to stay editable.

It is intentionally incomplete. The point is to capture ideas while they are still moving and make it easy to turn rough notes into real docs without rebuilding the whole site every time.

Work locally

Install

npm install

Develop

npm run dev

Build

npm run build

Preview

npm run preview

What lives where

Configuration

astro.config.mjs defines the site URL, sidebar, and global Starlight setup.

Core docs

src/content/docs/ is where the docs live. Most pages can stay in Markdown, and MDX is there when Starlight components genuinely make the page easier to read.

Reusable UI

src/components/docs/ is where small Astro components live when patterns start repeating across pages.

Styling

src/styles/custom.css is for light theme tuning without fighting the Starlight defaults.

Current docs shape

• Directorysrc/

  • Directorycomponents/

    • Directorydocs/

      • FieldNote.astro
      • PromptPanel.astro
  • Directorycontent/

    • Directorydocs/

      • Directoryauthoring/

        • …
      • Directoryfoundations/

        • …
      • Directoryarchitecture/

        • …
      • Directoryrunbooks/

        • …
      • Directorydeploy/

        • …
      • Directoryreference/

        • …
      • Directoryexamples/

        • …

How this site came together

1. Use catalyst-ops as a compass for the first topics instead of trying to copy over a full corpus.
2. Shape the docs tree around recurring themes: foundations, architecture, runbooks, deploy, reference.
3. Lean on MDX and Starlight components where structure helps, and keep terse lookup pages simple.
4. Add Astro components only when a pattern is actually repeating.

Open the page templates