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

A theme has the following layout:

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

Creating a site from a theme follows these steps:

  1. create-astro scaffolds the project from the template
  2. 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

The following command scaffolds a site from an official theme template:

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

Community themes hosted on GitHub use the github: template prefix:

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

After scaffolding, install dependencies and start the dev server:

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 performs these steps:

  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

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 Workers with D1 and R2, append -cloudflare to the template name, as in the following commands:

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, the 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. After that, manage the content model in the admin panel or with the CLI.

Next Steps