# Selective Deployment

Deploy a subset of your sitemd pages instead of the full site. Use this when sitemd manages part of your domain — like `/blog` and `/docs` — while another system handles the rest.

## When to use it

You have an existing site at `example.com` built with another tool. You want sitemd to power specific sections:

- A blog at `/blog`
- Documentation at `/docs`
- A handful of standalone pages like `/changelog`

Without selective deployment, sitemd builds every page in your project and deploys the entire output. With `deployPages`, only the pages you specify make it to the output — everything else is excluded from the build, sitemap, search index, and deploy.

## Configure deployPages

Add a `deployPages` list to `settings/deploy.md`. Each entry is a [group](/docs/groups) name or a URL path:

```yaml
# settings/deploy.md
---
domain: example.com
target: cloudflare

deployPages:
  - blog
  - docs
---
```

This builds only pages that belong to the `blog` or `docs` groups. All other pages are excluded.

### Matching rules

| Entry | What it matches |
|---|---|
| `blog` | Pages with `groupMember: [blog]` in frontmatter |
| `docs` | Pages with `groupMember: [docs]` in frontmatter |
| `/changelog` | The page with slug `/changelog` exactly |
| `/tools` | The page at `/tools` and any page under `/tools/...` |

Group names and path prefixes can be mixed freely:

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

### What gets included

When `deployPages` is set:

- **Matching pages** — built and written to the output directory
- **Theme assets** — always included (`/theme/styles.css`, fonts, scripts)
- **Media files** — always included (`/media/` directory)
- **Sitemap, search index, llms.txt** — only contain the deployed pages
- **Navigation** — renders as configured in `settings/header.md` (you control what links appear)

When `deployPages` is not set or empty, all pages deploy as normal.

## Set up your hosting

After sitemd builds the filtered output, you deploy it to your hosting platform. Your hosting provider routes specific paths to sitemd's deployment while serving the rest from your primary site.

### Cloudflare Pages

Deploy sitemd to a Pages project, then use a route rule on your main domain to proxy specific paths:

1. Deploy your sitemd output to a Cloudflare Pages project (e.g., `my-docs.pages.dev`)
2. In your main domain's Cloudflare settings, add a **Page Rule** or **Transform Rule** that proxies `/docs/*` and `/blog/*` to the Pages project

### Netlify

Use Netlify's `_redirects` file on your primary site to proxy paths to your sitemd deployment:

```text
/blog/*  https://my-sitemd-blog.netlify.app/blog/:splat  200
/docs/*  https://my-sitemd-docs.netlify.app/docs/:splat  200
```

The `200` status makes this a rewrite (proxy), not a redirect — visitors stay on your domain.

### Vercel

Add path rewrites to your primary site's `vercel.json`:

```json
{
  "rewrites": [
    { "source": "/blog/:path*", "destination": "https://my-sitemd.vercel.app/blog/:path*" },
    { "source": "/docs/:path*", "destination": "https://my-sitemd.vercel.app/docs/:path*" }
  ]
}
```

### GitHub Pages

GitHub Pages doesn't support path-level proxying. To use selective deployment with GitHub Pages, deploy sitemd to a project repository and access it at `username.github.io/repo-name`.

## Common patterns

### Blog only

One group, one section of your site:

```yaml
deployPages:
  - blog
```

Pages in `pages/blog/` with `groupMember: [blog]` are deployed. Set up your [navigation](/docs/navigation) to link within the blog and to external URLs for the rest of your site.

### Blog and docs from one project

Two groups, two sections:

```yaml
deployPages:
  - blog
  - docs
```

Both groups deploy. Each section gets its own [sidebar](/docs/groups) and navigation. Theme assets are shared.

### Groups plus standalone pages

Mix groups with individual paths for pages that don't belong to a group:

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

## Auth pages

If your deployed sections use [gated content](/docs/user-auth), include the auth pages in your deploy scope. Auth pages live in `auth-pages/` and typically aren't in any group, so add them by path:

```yaml
deployPages:
  - docs
  - /login
  - /register
  - /access-denied
```

## Settings reference

| Setting | Type | Default | Description |
|---|---|---|---|
| `deployPages` | list | *(empty — deploy all)* | Groups and/or URL paths to include in the build output. When empty or absent, all pages deploy. |

Each list entry is either:
- A **group name** (no leading `/`) — matches pages with that group in `groupMember`
- A **URL path** (starts with `/`) — matches the exact slug or any slug under that prefix

See [Deploy](/docs/deploy) for the full deployment configuration and [Groups](/docs/groups) for how page groups work.