Project Structure

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

my-site/
  sitemd/              ← All product code and content
    engine/            ← Build system, CLI, deploy targets
    pages/             ← Your markdown pages
    settings/          ← Site configuration
    theme/             ← HTML templates and CSS
    media/             ← Images and assets
    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
  .claude/skills/sitemd/  ← Single sitemd skill for Claude Code

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:

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 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 sitemd build system, CLI, and deploy targets. Installed as an npm package (@sitemd-cc/sitemd). Run sitemd update to fetch 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.

Agent integration files

Created by sitemd init:

.claude/skills/sitemd/ — Single sitemd skill for Claude Code
.cursor/ — Cursor IDE integration: rules/ (auto-attaching .mdc rule files) and skills/ (sitemd skill). See Cursor.

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

How does sitemd find the project?

Run CLI commands from anywhere inside your project — sitemd walks up from your current directory looking for a sitemd/settings/ directory and uses that as the project root. All paths to pages/, settings/, theme/, and site/ are resolved from there.

Keeping sitemd up to date

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