| name | site-infra |
| description | Capsem documentation site infrastructure and conventions. Use when writing, editing, or maintaining docs in the docs/ directory (docs.capsem.org), adding new doc pages, updating the sidebar, or working with Astro Starlight. Covers site structure, frontmatter, writing style, sidebar config, release pages, and dev workflow. |
Documentation Site
The documentation site (docs.capsem.org) uses Astro Starlight (Astro 6 + Tailwind v4). Docs live in docs/src/content/docs/ as markdown/MDX files.
Dev workflow
cd docs && pnpm run dev
cd docs && pnpm run build
CI and deploy rail
ci.yaml runs the merge-blocking docs-build job under pr-gate. docs.yaml
deploys only on every push to main and smokes https://docs.capsem.org/ plus
/getting-started/. This deploy rail is independent from binary releases,
manual VM asset releases, and the release.capsem.org asset-channel workflow.
Writing style
Tight and to the point, like a manual. One topic per page. No filler, no marketing language. Tables over prose when listing configs or test cases. Code examples only when they clarify usage. Diagrams in mermaid.
Frontmatter
Every doc page must include title and description. Starlight handles lastUpdated from git history automatically. No layout: field -- Starlight provides its own.
---
title: Page Title
description: One-line summary for SEO and sidebar tooltips.
sidebar:
order: 10
---
Site structure
docs/src/content/docs/
getting-started.md
architecture/
hypervisor.md Hypervisor abstraction, Apple VZ + KVM backends (5 mermaid diagrams)
settings.md Settings grammar, value resolution, presets, IPC, boot injection
build-system.md capsem-builder architecture, TOML configs, Jinja, multi-arch
custom-images.md Corporate image customization guide
settings-schema.md Two-node schema, JSON Schema, Pydantic, cross-language conformance
security/
overview.md Security model overview
network-isolation.md Air-gapped networking, domain policy
virtualization.md VM isolation guarantees
build-verification.md Build reproducibility, checksums
kernel-hardening.md Custom kernel, allnoconfig, minimal attack surface
benchmarks/
results.md Current performance results (boot, disk, CLI, HTTP, snapshots)
debugging/
capsem-doctor.md In-VM diagnostic suite
troubleshooting.md Common issues and solutions
development/
benchmarking.md How to run and extend capsem-bench
getting-started.md Dev environment setup (stub)
skills.md AI agent skills system
releases/
0-8.md through 0-14.md One page per minor version
Sidebar
Configured in docs/astro.config.mjs under starlight({ sidebar: [...] }). Uses autogenerate: { directory: '<category>' } for each section. Page ordering within a section uses sidebar: { order: N } in frontmatter.
Adding a new doc page
- Create
docs/src/content/docs/<category>/<topic>.md with frontmatter
- It auto-appears in the sidebar via
autogenerate
- Set
sidebar: { order: N } to control position (lower = higher in list)
Adding a new category
- Create the directory under
docs/src/content/docs/
- Add a sidebar entry in
docs/astro.config.mjs:
{ label: 'Category Name', autogenerate: { directory: 'category-slug' } }
Release pages
- Path:
docs/src/content/docs/releases/<major>-<minor>.md (hyphens, not dots)
- Each page consolidates all patch releases for that minor version
- Higher
sidebar.order = newer = listed first (reverse-chrono)
- When bumping to a new minor, create a new page
Mermaid diagrams
The site uses astro-mermaid for rendering. Use fenced code blocks:
```mermaid
graph LR
A --> B --> C
```
Astro reference
Read references/astro.md for Astro framework patterns (components, content collections, SSR, CLI). From the official Astro team.
Theme
Custom CSS in docs/src/styles/custom.css. Accent colors and fonts. Logo at docs/src/assets/logo.svg.
Graphics and icons
Source of truth for all icons: graphics/ at the project root.
graphics/
icon/ Brand icon in multiple sizes and variants
icon-mainfile.ai Illustrator source file
22w/ 22px (menu bar)
1x/ 726px (standard)
2x/ 1450px (retina)
3x/ 2176px
4x/ 2900px
1024w/ 1024px (app store, high-res)
Variants: capsem-logo-{black,color,grey,white}.png
tauri/ Pre-built Tauri app icon set
32x32.png, 128x128.png, 128x128@2x.png
icon.icns, icon.ico, icon.svg
Site favicons in docs/public/ are generated from graphics/icon/1024w/capsem-logo-color.png. To regenerate:
sips -z 16 16 graphics/icon/1024w/capsem-logo-color.png --out docs/public/favicon-16x16.png
sips -z 32 32 graphics/icon/1024w/capsem-logo-color.png --out docs/public/favicon-32x32.png
sips -z 180 180 graphics/icon/1024w/capsem-logo-color.png --out docs/public/apple-touch-icon.png
sips -z 192 192 graphics/icon/1024w/capsem-logo-color.png --out docs/public/android-chrome-192x192.png
sips -z 512 512 graphics/icon/1024w/capsem-logo-color.png --out docs/public/android-chrome-512x512.png
Drafts
tmp/build_sprint/custom-images.md -- 443-line draft for the custom images doc. Covers quick start, config reference, CLI reference, manifest, corporate deployment, troubleshooting.
Page scope boundaries
development/getting-started.md is strictly about environment setup: prerequisites, clone, bootstrap, build-assets, codesign, first run. Troubleshooting in this page must be limited to setup failures (doctor, codesign, build-assets OOM/clock, missing assets). Runtime issues (disk full, boot hangs, cross-compile errors, network problems) belong in debugging/troubleshooting.md -- link there instead of duplicating.debugging/troubleshooting.md is the catch-all for runtime issues. New troubleshooting entries go here unless they are specifically about first-time env setup.
Keep docs in sync
When features change (settings, CLI flags, MCP tools, security invariants, benchmarks), update the corresponding doc page. When cutting a new minor release, create a new release page. Most pages are still stubs -- fill them in as features stabilize.
