sitemd.cc

Getting Started

From zero to a running site in under a minute. sitemd works with any AI coding agent — Claude Code, Codex, Cursor, Gemini, VS Code, etc.

Install Method

Pick whichever method suits your workflow. Both produce the same project structure with a sitemd/ directory containing the engine, theme, templates, and a working demo site on localhost.

Scaffold a new project with a single command:

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

The npm method downloads the sitemd binary for your platform automatically via the package's postinstall hook — no separate install step required.

GitHub

Clone the repo and install dependencies:

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

Requirements

sitemd requires Node.js. Install globally via npm i -g @sitemd-cc/sitemd or use npx. Optional npm dependencies (icons, image processing) are auto-installed 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:

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:

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

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

---
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 for matching rules, hosting setup, and common patterns.

Connect your agent

sitemd exposes all its functionality through CLI commands that any AI coding agent can use via a single sitemd skill. If you scaffolded via npx @sitemd-cc/sitemd init, the site.md context file and .claude/skills/sitemd/ skill are already wired up — open the project in your agent and you're done. The notes below cover edge cases and the optional marketplace plugins.

Claude Code

The npx init scaffold ships with a site.md and .claude/skills/sitemd/ at the project root, so opening the project in Claude Code is enough — no plugin install required. If you'd also like the marketplace plugin (registers the plugin name in /plugin list), run inside the project:

/plugin install sitemd

Note: the plugin alone does not install sitemd — it expects a sitemd project already on disk. Use npx @sitemd-cc/sitemd init for a fresh start.

Cursor, VS Code

The site.md file at your project root is read automatically. No extra setup — open the project and your agent has access to all sitemd CLI commands.

Codex CLI

Install the sitemd plugin:

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 CLI tools can use sitemd. Point it at the sitemd CLI — see CLI for details.

Set up your project

Ask your agent to set up a new sitemd site. It will run sitemd status and walk you through the setup — site name, description, which sections you want — and create your project structure. See Project Structure for the full directory reference.

Write your first page

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

---
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 run the right CLI commands automatically.

Or run it from the CLI:

sitemd launch

Your site is now running at http://localhost:4747. Open it in your browser. Press ⌘/ to open the Dev Panel and start editing directly in the browser.

What's next