# Getting Started

From zero to a running site in under a minute. sitemd works with any AI coding agent that uses skills, MCP, or CLI — Claude Code, Codex, Cursor, Gemini, OpenClaw, VS Code, etc.

card: Install Method +banner
card-icon: circle-question-mark
card-text: Pick whichever method suits your workflow. All three produce the same project structure with a `sitemd/` directory containing the binary, theme, templates, and a working demo site on `localhost`.

### npm (recommended)

Scaffold a new project with a single command:

```bash
npx @sitemd-cc/sitemd init my-site
cd my-site
sitemd launch
```

### GitHub

Clone the repo and run the install script to download the binary for your platform:

```bash
git clone https://github.com/sitemd-cc/sitemd.git my-site
cd my-site
./sitemd/install
./sitemd/sitemd launch
```

### Download

Grab a `.tar.gz` or `.zip` archive from [sitemd.cc/install](https://sitemd.cc/install), extract it, and run:

```bash
cd my-site
./sitemd/install
./sitemd/sitemd launch
```

### Requirements

sitemd ships as a compiled binary with no runtime dependencies. The npm method requires Node.js; the GitHub and Download methods do not. Optional npm dependencies (icons, image processing) are [auto-installed](/docs/dependencies) when you first launch the dev server.

## New project vs existing project

### Starting fresh

Every install method above creates a self-contained project with a `sitemd/` directory containing a blank-slate homepage, default settings, and a ready-to-use theme. Run the dev server and start adding pages.

To reset an existing project back to this blank state at any time:

```bash
sitemd scratch
```

This replaces `sitemd/pages/` and `sitemd/settings/` with the blank-slate defaults. Engine, theme, and media are preserved.

### Adding sitemd to an existing project

Run `sitemd init` from outside your project, then move the `sitemd/` directory into your existing project root:

```bash
npx @sitemd-cc/sitemd init temp-sitemd
mv temp-sitemd/sitemd ./sitemd
```

Then run `sitemd setup` to create the agent integration files (`.mcp.json`, `CLAUDE.md`, skills). Once a `sitemd/settings/` directory exists, sitemd recognizes the project and all CLI commands work.

## Full site vs partial site

### Full site on sitemd

The default. Every `.md` file in `sitemd/pages/` becomes a page on your domain. sitemd handles the homepage, navigation, blog, docs, and everything else. This is the simplest setup — one build system, one deploy.

### Only certain sections on sitemd

Use [Selective Deployment](/docs/selective-deployment) when another system already manages your domain and you want sitemd to power specific sections like `/blog` or `/docs`.

Add a `deployPages` list to `sitemd/settings/deploy.md`:

```yaml
---
deployPages:
  - blog
  - docs
  - /changelog
---
```

Only matching pages are included in the build output, sitemap, and deploy. Everything else is excluded. Your hosting platform routes these paths to sitemd's output while the rest of your domain stays on its existing system.

See [Selective Deployment](/docs/selective-deployment) for matching rules, hosting setup, and common patterns.

## Connect your agent

sitemd exposes all its functionality through an [MCP server](/docs/mcp-server) that any MCP-capable agent can use. The setup depends on your agent:

### Claude Code

Install the sitemd plugin:

```text
/plugin install sitemd
```

This gives Claude Code the knowledge and commands to build your site.

### Cursor, VS Code

The `.mcp.json` file at your project root is read automatically. Run `sitemd setup` if the file doesn't exist yet. No extra setup — open the project and your agent has access to all sitemd tools.

### Codex CLI

Install the sitemd plugin:

```text
codex plugin install sitemd
```

### Gemini CLI

The `gemini-extension.json` at the project root is read automatically. Open the project and start building.

### Other agents

Any agent that supports MCP can use sitemd. Point it at the MCP server via `./sitemd/sitemd mcp` — see [MCP Server](/docs/mcp-server) for details.

## Set up your project

Ask your agent to set up a new sitemd site. It will call `sitemd_status` and walk you through the setup — site name, description, which sections you want — and create your project structure. See [Project Structure](/docs/project-structure) for the full directory reference.

Or run it directly from the CLI:

```bash
sitemd setup
```

## Write your first page

Open `sitemd/pages/home.md`. You'll see frontmatter at the top and content below:

```markdown
---
title: My Site
description: A short description of my site.
slug: /
layout: default
---

# Welcome to my site

Your content goes here. Write in markdown.
```

The frontmatter controls metadata — title, description, URL slug, and layout. The body is your content, written in standard markdown.

## Build and preview

Ask your agent to build and launch the dev server. It will call the right MCP tools automatically.

Or run it from the CLI:

```bash
sitemd launch
```

Your site is now running at `http://localhost:4747`. Open it in your browser. Press **⌘/** to open the [Dev Panel](/docs/dev-panel) and start editing directly in the browser.

## What's next

- **Add more pages** — Create new `.md` files in `sitemd/pages/`. Each file becomes a page.
- **Configure navigation** — Edit `sitemd/settings/header.md` to control what appears in the header. Just add a label and the page is created for you. See [Navigation](/docs/navigation).
- **Customize the theme** — Edit `sitemd/settings/meta.md` for identity, or modify `sitemd/theme/styles.css` for visual changes.
- **Add a docs section** — Create `sitemd/pages/docs/` and add pages with `layout: docs` in frontmatter.
- **Add images** — Resize, crop, filter, and create galleries with simple modifiers. See [Images](/docs/images).
- **Import existing content** — Use the import command to convert any markdown file into a sitemd page with auto-generated frontmatter and group assignment. See [MCP Server](/docs/mcp-server).
- **Clone an existing site** — Scrape a website and import its content, navigation, and images. See [Website Cloning](/docs/clone).
- **Generate content** — Use the `/write` skill to generate docs, blog posts, changelogs, and more with built-in voice rules and quality checks. See [Content Generation](/docs/content-generation).
- **SEO is automatic** — Open Graph tags, structured data, sitemaps, and favicons are generated on every production build. See [SEO](/docs/seo).
- **Add user login** — Gate pages behind authentication with Supabase, Firebase, Clerk, Auth0, or your own API. See [User Auth & Gating](/docs/user-auth).
- **Go live** — Trial mode is free on localhost. Authenticate and [activate your site](/docs/how-to-activate-site) to build for production. See [Build Modes](/docs/build-modes).
- **Deploy to production** — When you're ready to go live, [authenticate](/docs/authentication) and run `sitemd deploy`. See [Deploy](/docs/deploy).
- **Learn how agents onboard** — See how sitemd teaches your agent the full system automatically. See [Agent Onboarding](/docs/agent-onboarding).