Build and customize EmDash CMS sites on Astro. Use when creating pages, defining collections, writing seed files, querying content, rendering Portable Text, setting up menus/taxonomies/widgets, configuring deployment, or any task involving an EmDash-powered Astro site. Assumes basic Astro knowledge but provides all EmDash-specific patterns.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Build and customize EmDash CMS sites on Astro. Use when creating pages, defining collections, writing seed files, querying content, rendering Portable Text, setting up menus/taxonomies/widgets, configuring deployment, or any task involving an EmDash-powered Astro site. Assumes basic Astro knowledge but provides all EmDash-specific patterns.
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.
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".
entry.id vs entry.data.id are different things.entry.id is the slug (use in URLs). 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.
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.
Always pass cacheHint to . Every query returns a . Call on every page that queries content, or cache invalidation won't work when editors publish changes.
Astro.cache.set()
cacheHint
Astro.cache.set(cacheHint)
No getStaticPaths for CMS content. EmDash content is dynamic. Pages must be server-rendered (output: "server" in astro.config.mjs).
Read 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 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 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 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. Validate with:
npx emdash seed seed/seed.json --validate
6. Run and verify
npx emdash dev # Start dev server (runs migrations + seeds, and generates types)
The admin UI is at http://localhost:4321/_emdash/admin.
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 custom block types to the Portable Text editor (e.g., embedded maps, code playgrounds, CTAs)
Provide a reusable service (e.g., analytics, forms, comments via a third-party provider)
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.
