Themes Overview

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

Note

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.

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

For Users

Pick a theme, run the wizard, start editing. No database knowledge required.

For Developers

Themes are standard Astro projects. Customize freely after scaffolding.

Installing a Theme

Use create-astro with a template:

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

Community themes work via GitHub:

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

After installation:

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              │
└────────────────────────────────────────────────────────┘

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.

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:

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 — Build your own EmDash theme
• Seed File Format — Reference for seed file structure
• Getting Started — Create your first EmDash site