# Project Structure

Everything sitemd needs lives in a single `sitemd/` directory at your project root.

```text
my-site/
  sitemd/              ← All product code and content
    pages/             ← Your markdown pages
    settings/          ← Site configuration
    theme/             ← HTML templates and CSS
    media/             ← Images and assets
    engine/            ← Build system and MCP server
    templates/         ← Reset templates (scratch, demo)
    auth-pages/        ← Login, signup, forgot-password (opt-in)
    account-pages/     ← User dashboard (opt-in)
    gated-pages/       ← Authenticated-only content (opt-in)
    modals/            ← Global modal dialogs
    site/              ← Built output (gitignored)
  site.md              ← Quick start and agent context
```

## What goes where?

### `sitemd/pages/`

Every `.md` file becomes a page on your site. The URL is derived from the file path or the `slug` field in frontmatter. Subdirectories create URL segments — `pages/docs/getting-started.md` becomes `/docs/getting-started`.

See [Pages & Content](/docs/pages-and-content) for the full page format reference.

### `sitemd/settings/`

YAML frontmatter files that control your site. Each file handles one concern:

| File | Controls |
|---|---|
| `meta.md` | Site name, description, URL, logo, favicon |
| `header.md` | Navigation items, buttons, search, auth button |
| `footer.md` | Footer content, social links, copyright |
| `groups.md` | Page groups for sidebars, dropdowns, footer columns |
| `theme.md` | Colors, fonts, CSS variables, light/dark mode |
| `build.md` | Dev server port, build mode |
| `seo.md` | Sitemap, robots, OG images, structured data |
| `deploy.md` | Deploy target, selective deployment |
| `auth.md` | Authentication provider |
| `forms.md` | Form defaults |
| `email.md` | Email provider |
| `analytics.md` | Analytics provider |
| `data.md` | Dynamic data sources |
| `content.md` | Content generation settings |

See [Site Identity](/docs/site-identity) for `meta.md` and the individual docs for each setting.

### `sitemd/theme/`

HTML layout templates and CSS. The default theme includes light, dark, and paper modes. Edit `styles.css` for visual changes or modify `layout.html` for structural changes.

See [Themes](/docs/themes) for customization options.

### `sitemd/media/`

Images and other assets. Reference them in your pages as `/media/filename.jpg`. For production sites, [Media Hosting](/docs/media-hosting) can sync this directory to a CDN.

### `sitemd/engine/`

The build system, CLI, MCP server, and deploy targets. Do not edit files in this directory — they are replaced during updates. Run `sitemd update` to get the latest version. See [Updates](/docs/updates).

### `sitemd/templates/`

Bundled templates for resetting your project. `scratch/` is the blank-slate template. `demo/` is the component showcase. Run `sitemd scratch` to reset your pages and settings to the blank-slate defaults.

### Other directories

- **`auth-pages/`** — Login, signup, and forgot-password page templates. Created when you enable auth with `sitemd_auth_setup`. Customizable markdown with the same frontmatter as regular pages.
- **`account-pages/`** — User dashboard pages for authenticated users. Created by `sitemd_auth_setup`.
- **`gated-pages/`** — Pages only accessible to specific user types. Created by `sitemd_auth_setup`. See [User Auth & Gating](/docs/user-auth).
- **`modals/`** — Global modal dialogs available on every page. See [Tooltips & Modals](/docs/tooltips-modals).

## Root-level files

### `site.md`

A single file at your project root with quick start instructions and agent context. Both humans and AI agents read this file to understand the project.

### `.mcp.json`

Created by `sitemd setup`. Tells MCP-capable agents (Claude Code, Cursor, VS Code, Codex) where the sitemd MCP server lives. The file is a standard MCP configuration:

```json
{
  "mcpServers": {
    "sitemd": {
      "command": "./sitemd/sitemd",
      "args": ["mcp"]
    }
  }
}
```

If you already have a `.mcp.json` with other servers, `sitemd setup` merges the sitemd entry without overwriting your existing configuration.

### Agent context files

Created by `sitemd setup`:

- **`CLAUDE.md`** — Context for Claude Code with the full sitemd reference
- **`AGENTS.md`** — Same context in a generic format for other agents
- **`.agents/skills/`** — Agent skills in the generic multi-agent format
- **`.claude/skills/`** — Agent skills for Claude Code
- **`.cursor/`** — Cursor IDE integration: `mcp.json`, `rules/` (3 auto-attaching `.mdc` rule files), and `skills/` (12 skills). See [Cursor](/docs/cursor).
- **`.cursor-plugin/`** — Cursor marketplace manifest for plugin discovery

These files are appended or merged if they already exist — setup never overwrites your existing agent configuration.

## How does `sitemd setup` work?

Run `sitemd setup` to create the agent integration files at your project root. This configures `.mcp.json`, copies agent context files, and checks for missing dependencies.

```bash
sitemd setup
```

Setup runs automatically on your first `sitemd launch` if it detects no existing `.mcp.json` configuration. You can also re-run it manually at any time to update agent files after an engine update.

If you installed via `git clone` from the public repository, these files are already present. For npm and download installations, setup creates them automatically on first launch.

## How does the engine find the project?

The engine resolves its project root from its own location: `sitemd/engine/` → two directories up → `sitemd/`. All paths to `pages/`, `settings/`, `theme/`, and `site/` are relative to this root.

The CLI's `findRoot` function walks up from your current directory looking for a `sitemd/settings/` directory. Run CLI commands from anywhere inside your project — it finds the right root automatically.

## Keeping sitemd up to date

Run `sitemd update` to check for and apply engine updates. This replaces `sitemd/engine/` and `sitemd/theme/` with the latest versions while leaving your pages, settings, and media untouched. See [Updates](/docs/updates).