E EmDash CMS Everything Guides, use cases, plugins, templates
English

Themes Overview

On this page

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

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:    [[email protected]                  ] │
│  Admin Password: [••••••••••••                       ] │
│                                                        │
│  ☑ Include sample content                              │
│                                                        │
│                   [Create Site →]                      │
│                                                        │
│  Template: Blog Starter                                │
│  Creates: 2 collections, 3 pages, 1 post              │
└────────────────────────────────────────────────────────┘

Official Themes

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

ThemeDescriptionUse Case
@emdash-cms/template-blogMinimal blog with posts, pages, categories, and dark modePersonal blogs, simple sites
@emdash-cms/template-portfolioEditorial-style portfolio with projects, serif typography (Playfair Display), and image-focused layoutsFreelancers, agencies, creatives
@emdash-cms/template-marketingBold 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