Project Structure

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

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 for the full page format reference.

sitemd/settings/

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

See 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 for customization options.

sitemd/media/

Images and other assets. Reference them in your pages as /media/filename.jpg. For production sites, 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.

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.
• modals/ — Global modal dialogs available on every page. See 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:

{
  "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.
• .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.

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.