# Live Build Sync

Save any file in your site and the build runs automatically. Edit `settings/theme.md` and `theme/styles.css` updates itself. No manual steps.

## How it works

Running `sitemd launch` (or `./sitemd/sitemd launch`) starts a dev server with a file watcher on three directories:

- `settings/` — syncs theme settings to CSS, then rebuilds
- `pages/` — rebuilds the site
- `theme/` — rebuilds the site

Changes are debounced at 150ms so rapid saves don't cause redundant rebuilds.

## Theme sync

Every value in the `light:`, `dark:`, and `paper:` blocks of `settings/theme.md` maps to a CSS custom property in the matching `[data-theme="..."]` block in `styles.css`.

```yaml
# settings/theme.md
paper:
  color-bg: #f8f5d7
  color-accent: #3a6d78
```

```css
/* theme/styles.css — updated automatically */
[data-theme="paper"] {
  --color-bg: #f8f5d7;
  --color-accent: #3a6d78;
}
```

Top-level settings sync to the `:root` block:

| Setting | CSS Variable |
|---|---|
| `fontSans` | `--font-sans` |
| `fontMono` | `--font-mono` |
| `contentWidth` | `--content-width` |
| `pageWidth` | `--page-width` |
| `radius` | `--radius` |

The sync also runs on every `sitemd build` invocation, not just during `launch`.

## Source of truth

`settings/theme.md` is the source of truth for all theme values. If you edit `styles.css` directly, your changes will be overwritten on the next build if the same property exists in `theme.md`.

To make permanent changes:

1. Edit the value in `settings/theme.md`
2. Save — the CSS updates automatically
3. That's it

If you need a CSS property that isn't in `theme.md` (like font sizes, spacing, transitions), edit `styles.css` directly. The sync only touches properties that have a corresponding setting.

## Live reload

The dev server injects a lightweight script into every page that listens for rebuild events via Server-Sent Events. When any file changes and the build completes, your browser refreshes automatically — no manual reload needed.

This works for all watched directories: edit a settings file, update page content, or modify the theme, and the browser reflects the change within moments.

You can also edit files directly in the browser using the built-in [Dev Panel](/docs/dev-panel) — toggle it with ⌘/ and save with ⌘S without leaving the browser.

## Build script changes

If any file in `engine/build/` is modified, the dev server detects the change and restarts its own process. Code-level changes to the build system take effect without manually stopping and restarting the server.

## File auto-rename

If a page's `slug` frontmatter doesn't match its filename, the build renames the file to match. Change `slug: /docs/setup` to `slug: /docs/getting-started` and the file moves from `pages/docs/setup.md` to `pages/docs/getting-started.md` on the next build. Stale sidebar entries are cleaned up automatically.

See [Pages & Content](/docs/pages-and-content#slug-based-auto-rename) for details.

## Page auto-scaffold

When you add a navigation item to `settings/header.md`, the build creates any missing page files automatically. Add `- About` to your nav items and `pages/about.md` appears on the next build. Group children are nested under the group folder — `pages/product/features.md` for a child of the `Product` group.

See [Navigation](/docs/navigation) for the full details on auto-scaffolding, dropdown groups, and CTA buttons.