---
title: Themes Overview
description: Understand how EmDash themes work and how they bootstrap new sites.
---

import { Aside, Card, CardGrid } from "@astrojs/starlight/components";

An EmDash theme is a complete Astro site -- pages, layouts, components, styles -- distributed via `create-astro`. It also includes a **seed file** that bootstraps the database with collections, fields, menus, redirects, and sample content on first run.

## What a Theme Provides

A theme is a working Astro project with:

- **Pages** — Astro routes for rendering content (homepage, blog posts, archives, etc.)
- **Layouts** — Shared HTML structure
- **Components** — Reusable UI elements (navigation, cards, footers)
- **Styles** — CSS or Tailwind configuration
- **A seed file** — JSON that tells the CMS what content types and fields to create

<Aside>
	EmDash gives you far more control over the content model than WordPress does. Themes take
	advantage of this by declaring exactly which collections and fields they need via the seed file.
	Most themes should build on the standard **posts** and **pages** collections, adding fields and
	taxonomies as needed rather than inventing entirely new content types.
</Aside>

## Theme Structure

```
my-theme/
├── package.json           # Theme metadata + EmDash config
├── astro.config.mjs       # Astro integration setup
├── src/
│   ├── live.config.ts     # Live Collections configuration
│   ├── pages/             # Astro routes
│   ├── layouts/           # Layout components
│   └── components/        # UI components
└── .emdash/
    ├── seed.json          # Schema + sample content
    └── uploads/           # Optional local media files
```

## How Themes Bootstrap Sites

When you create a site from a theme, this happens:

1. `create-astro` scaffolds the project from the template
2. You run `npm install` and `npm run dev`
3. On first admin visit, the **Setup Wizard** runs automatically
4. The wizard applies the seed file, creating collections, menus, redirects, and content
5. The site is ready to use

<CardGrid>
	<Card title="For Users" icon="laptop">
		Pick a theme, run the wizard, start editing. No database knowledge required.
	</Card>
	<Card title="For Developers" icon="seti:config">
		Themes are standard Astro projects. Customize freely after scaffolding.
	</Card>
</CardGrid>

## Installing a Theme

Use `create-astro` with a template:

```bash
npm create astro@latest -- --template @emdash-cms/template-blog
```

Community themes work via GitHub:

```bash
npm create astro@latest -- --template github:user/emdash-portfolio
```

After installation:

```bash
cd my-site
npm install
npm run dev
```

Visit `http://localhost:4321/_emdash/admin` to complete the Setup Wizard.

## The Setup Wizard

The Setup Wizard runs automatically on first admin visit. It:

1. Prompts for site title, tagline, and admin credentials
2. Offers an option to include sample content
3. Applies the seed file to the database
4. Redirects to the admin dashboard

```
┌────────────────────────────────────────────────────────┐
│                                                        │
│                    ◆ EmDash                          │
│                                                        │
│              Welcome to your new site                  │
│                                                        │
│  Site Title:     [My Awesome Blog                    ] │
│  Tagline:        [Thoughts and ideas                 ] │
│                                                        │
│  Admin Email:    [admin@example.com                  ] │
│  Admin Password: [••••••••••••                       ] │
│                                                        │
│  ☑ Include sample content                              │
│                                                        │
│                   [Create Site →]                      │
│                                                        │
│  Template: Blog Starter                                │
│  Creates: 2 collections, 3 pages, 1 post              │
└────────────────────────────────────────────────────────┘
```

<Aside type="tip">
	Check "Include sample content" when exploring a theme for the first time. The sample content
	demonstrates how the theme expects content to be structured.
</Aside>

## Official Themes

EmDash provides official starter themes, each available in local (SQLite + filesystem) and Cloudflare (D1 + R2) variants:

| Theme | Description | Use Case |
| ----- | ----------- | -------- |
| `@emdash-cms/template-blog` | Minimal blog with posts, pages, categories, and dark mode | Personal blogs, simple sites |
| `@emdash-cms/template-portfolio` | Editorial-style portfolio with projects, serif typography (Playfair Display), and image-focused layouts | Freelancers, agencies, creatives |
| `@emdash-cms/template-marketing` | Bold marketing site with custom Portable Text blocks (hero, features, testimonials, pricing, FAQ) | Landing pages, SaaS sites, product marketing |

### Cloudflare Variants

For deployment on Cloudflare Pages with D1 and R2, append `-cloudflare` to the template name:

```bash
npm create astro@latest -- --template @emdash-cms/template-blog-cloudflare
npm create astro@latest -- --template @emdash-cms/template-portfolio-cloudflare
npm create astro@latest -- --template @emdash-cms/template-marketing-cloudflare
```

These variants include `wrangler.jsonc` for deployment configuration.

## Customizing After Install

After the Setup Wizard completes, your site is a standard Astro project. Customize it like any Astro site:

- Edit pages in `src/pages/`
- Modify layouts in `src/layouts/`
- Add collections via the admin UI
- Install Astro integrations
- Deploy anywhere Astro runs

The seed file is only used during initial setup. Once applied, your schema lives in the database.

## Next Steps

- **[Creating Themes](/themes/creating-themes/)** — Build your own EmDash theme
- **[Seed File Format](/themes/seed-files/)** — Reference for seed file structure
- **[Getting Started](/getting-started/)** — Create your first EmDash site
