emdash-cms/emdash

building-emdash-site

Build the site-facing parts of an EmDash CMS project on Astro, including schema and seeds, content queries, Portable Text rendering, menus, taxonomies, widgets, and deployment configuration.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/emdash-cms/emdash --skill building-emdash-site

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Building an EmDash Site

EmDash is a CMS built on Astro. It stores schema in the database (not in code), serves content via live content collections, and provides a full admin UI at /_emdash/admin. Sites are standard Astro projects with the emdash integration.

Common Gotchas

These are the things that silently break sites. Know them before you start.

  1. Image fields are objects, not strings. post.data.featured_image is { id, src, alt }. Writing <img src={post.data.featured_image} /> renders [object Object]. Use <Image image={post.data.featured_image} /> from "emdash/ui".
  1. `entry.id` vs `entry.data.id` are different things. entry.id is the slug, prefixed with the locale (en/my-post) for locales whose URLs are prefixed (use in URLs; entry.data.slug is the bare slug). entry.data.id is the database ULID (use for getEntryTerms, Comments, and other API calls that need the real ID). Mixing them up causes silent empty results.
  1. Taxonomy names must match the seed exactly. If your seed defines "name": "category", you must query getTerm("category", slug) -- not "categories". Wrong name = empty results, no error.
  1. Register cache hints when Astro's cache is enabled. Content queries return a cacheHint; pass it to Astro.cache.set(cacheHint). Use getSiteSettingsWithCacheHint(), getMenuWithCacheHint(), getTaxonomyTermsWithCacheHint(), and getWidgetAreaWithCacheHint() when a cached route renders those values.
  1. No `getStaticPaths` for CMS content. EmDash content is dynamic. Pages must be server-rendered (output: "server" in astro.config.mjs).

File Structure

Every EmDash site has these key files:

my-site/
├── astro.config.mjs          # Astro config with emdash() integration
├── src/
│   ├── live.config.ts         # EmDash loader registration (boilerplate)
│   ├── pages/                 # Astro pages (all server-rendered)
│   ├── layouts/               # Layout components
│   └── components/            # Reusable components
├── seed/
│   └── seed.json              # Schema + demo content
├── emdash-env.d.ts          # Generated types (from `emdash types`)
└── package.json

Workflow

1. Configure the project

Read [references/configuration.md](references/configuration.md) for astro.config.mjs, live.config.ts, deployment targets (Node vs Cloudflare), and type generation.

2. Design the schema

Read [references/schema-and-seed.md](references/schema-and-seed.md) for collection definitions, field types, taxonomies, menus, widget areas, sections, bylines, and the complete seed file format.

3. Build the pages

Read [references/querying-and-rendering.md](references/querying-and-rendering.md) for content queries, Portable Text rendering, the Image component, visual editing attributes, caching, and common page patterns (list, detail, taxonomy archive, RSS, search, 404).

4. Wire up site features

Read [references/site-features.md](references/site-features.md) for site settings, navigation menus, taxonomies, widget areas, search, SEO meta, comments, and page contributions.

5. Create the seed file

Write seed/seed.json with collections, fields, taxonomies, menus, widgets, and sample content.

6. Run and verify

bash
pnpm dev                # Start the Astro dev server

The runtime runs pending migrations on the first request and, before setup is completed, applies the seed's schema and structure once. Sample content needs an explicit step; see Applying Seeds. The Astro integration generates emdash-env.d.ts when the server starts. The admin UI is at http://localhost:4321/_emdash/admin.

Quick API Cheat Sheet

typescript
// Content (entries have .data.byline and .data.bylines eagerly loaded)
import { getEmDashCollection, getEmDashEntry } from "emdash";
const { entries, nextCursor, cacheHint } = await getEmDashCollection("posts", {
	limit: 10,
	cursor,
	orderBy: { published_at: "desc" },
});
const { entry: post, cacheHint: entryCacheHint } = await getEmDashEntry("posts", slug);

// Site features
import {
	getSiteSettings,
	getSiteSettingsWithCacheHint,
	getMenu,
	getMenuWithCacheHint,
	getTaxonomyTerms,
	getTaxonomyTermsWithCacheHint,
	getTerm,
	getEntryTerms,
	getEntriesByTerm,
	getWidgetArea,
	getWidgetAreaWithCacheHint,
	search,
	getSection,
	getSeoMeta,
} from "emdash";

// Bylines (standalone queries -- usually not needed since entries have bylines attached)
import { getByline, getBylineBySlug } from "emdash";

// UI components
import {
	PortableText,
	Blocks,
	defineBlockComponents,
	Image,
	WidgetArea,
	EmDashHead,
	EmDashBodyStart,
	EmDashBodyEnd,
} from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
import LiveSearch from "emdash/ui/search";

// Page context (for plugin contributions)
import { createPublicPageContext } from "emdash/page";

Plugins

EmDash supports plugins for extending the CMS with hooks, storage, settings, admin UI, API routes, and custom Portable Text block types. Consider a plugin when you need to:

  • React to content lifecycle events (e.g., send a notification on publish, sync to an external service)
  • Add custom admin pages or dashboard widgets
  • Add reusable behavior or custom Portable Text types (e.g., embedded maps or code playgrounds)
  • Provide a reusable service (e.g., analytics, forms, comments via a third-party provider)

Plugins are registered in astro.config.mjs:

javascript
emdash({
	database: sqlite({ url: "file:./data.db" }),
	storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }),
	plugins: [myPlugin()],
}),

To build a plugin, load the `creating-plugins` skill (in .agents/skills/creating-plugins/). It covers plugin anatomy, hooks, storage, admin UI, API routes, Portable Text blocks, capabilities, and the full definePlugin() API.

Reference Documents

FileContents
references/configuration.mdProject setup, astro.config, live.config, deployment, types
references/schema-and-seed.mdCollections, fields, taxonomies, menus, widgets, seed format
references/querying-and-rendering.mdContent APIs, PortableText, Image, caching, page patterns
references/site-features.mdSettings, menus, widgets, search, SEO, comments, page contributions
from this repository

More skills

All skills