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.

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

/* 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:

Edit the value in settings/theme.md
Save — the CSS updates automatically
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 — 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 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 for the full details on auto-scaffolding, dropdown groups, and CTA buttons.