`; that's what `getSeoMeta()` is for. ### Click-to-edit Every entry carries an `edit` proxy. Spread `entry.edit.<field>` onto the element rendering that field and a logged-in admin gets click-to-edit on the public page: ```astro <h1 {...post.edit.title}>{post.data.title}</h1> <div {...page.edit.content}><MarketingBlocks value={page.data.content} /></div> ``` Cheap to add, invisible to visitors, and it makes the theme feel integrated instead of bolted on. ## Step 8: seed content so the theme demos itself A theme that installs empty is a theme nobody evaluates. The `content` key seeds entries per collection; the home page seeds its blocks as literal values: ```json "content": { "pages": [ { "id": "home", "slug": "home", "status": "published", "data": { "title": "Home", "content": [ { "_type": "marketing_hero", "_version": 1, "_key": "home-hero", "headline": "EmDash tutorials, themes and plugins in one place", "specs": [{ "icon": "zap", "label": "Cloudflare Workers SSR" }] }, { "_type": "site_tutorials", "_version": 1, "_key": "home-tutorials", "headline": "Latest tutorials", "limit": 3 } ] } } ] } ``` Seed-content rules that save debugging time: - Give every block and span a stable `_key`; it's required, and duplicated keys produce broken editing behavior. - Image fields take `{ "$media": { "url": "...", "alt": "...", "filename": "..." } }`. EmDash downloads and stores the file. A bare URL string skips the download but renders. - Reference other seeded entries with `"$ref:seed-id"`, never raw IDs. - `"status": "draft"` seeds unpublished content for testing draft views. - `npx emdash export-seed --with-content` snapshots a working site back into a seed file. The fastest way to author `content` is to build the pages in the admin, then export. Seed is applied once, on first request to an empty database before setup completes; it never overwrites existing data. Schema changes to a live database go through [schema evolution](https://docs.emdashcms.com/deployment/schema-evolution/), not re-seeding. ## Step 9: the conventions that keep a theme coherent Small things, but they are where DIY themes drift: - **Icons.** Keep a fixed icon vocabulary. On emdashhq a `select` field's options map through `src/lib/icons.ts` (`ICON_MAP`) to Phosphor names, and every icon is also listed in the `astro-iconset` `include` config. That's three places per new icon: seed options, the map, the build list. Miss the build list and the icon silently doesn't ship. - **Stored URLs.** Anything an editor can type into a `url`/`string` field goes through `sanitizeHref()` before `href`. A `linkAttrs()` helper wraps it and adds `target="_blank" rel="noopener noreferrer"` to absolute web links. - **Images.** Always `<Image image={post.data.featured_image} />` from `emdash/ui`. `<img src={field}>` on an object renders `[object Object]`, the single most common EmDash template bug. - **Search.** `LiveSearch` from `emdash/ui/search` drops into the header; it only indexes collections with the `search` support and fields flagged `searchable`, and it's skinned with `--emdash-search-*` CSS variables so it matches the theme. - **Dark mode.** The cookie-toggle pattern: a tiny `is:inline` script in `<head>` adds `.light`/`.dark` (or nothing = follow OS) before paint, and `light-dark()` tokens do the rest. On emdashhq, `html:not(.light):not(.dark) { color-scheme: light dark }` overrides the admin stylesheet's `color-scheme: light` pin in system mode. Copy that fix or dark mode will stick light. <Notice type="warning" title="The five mistakes every new EmDash theme makes"> Image fields rendered as strings (`<img src={field}>`; use `<Image>`). Querying a taxonomy by the plural name (`"categories"` when the seed says `"category"` gives empty results with no error). Passing `entry.id` (the slug) where `data.id` (the ULID) is required, as in `getEntryTerms` and `Comments`. `getStaticPaths` on CMS routes: content is dynamic, so stay on `output: "server"`. And forgetting `Astro.cache.set(cacheHint)` on cached routes, which makes publish events not invalidate the page. </Notice> ## Verify the theme works <ListCheck> <ul> <li><code>npm run dev</code> regenerates <code>emdash-env.d.ts</code> with your new collection and block types</li> <li>The admin block picker shows your block types under their categories, with the fields you declared</li> <li>A page composed of seeded blocks renders on <code>/</code>; a new admin-created page works with no code change</li> <li>Menus, site title, and social links edited in the admin appear on the public site</li> <li>Click-to-edit works for a logged-in admin on rendered fields</li> <li>Both color modes render; no hard-coded light-only colors in components</li> <li><code>/definitely-missing</code> hits your 404 route, not a blank page</li> </ul> </ListCheck> ## Distributing the theme A finished theme is just a repo. To make it scaffoldable like the official ones, keep `package.json#emdash.seed` set, keep the template paths (`src/pages`, `src/layouts`, `src/components`, `seed/`), and someone else can run `npm create astro@latest -- --template your-org/your-repo`. The official `@emdash-cms/template-*` packages on npm work the same way. What ships is the code plus the seed; content always starts empty in the new owner's database. ## FAQ <Accordion label="blocks field or portableText — which one do I use?" group="faq" expanded="true"> Use `blocks` for page-level composition: an ordered stack of typed sections (hero, features, CTA) that editors add and reorder. Use `portableText` for document content: a post body, an about page, anything paragraph-flow. Custom objects inside rich text render through the `PortableText` component's `components.type` map and need a plugin for a custom editor UI; page-level blocks get their editing UI from the seed declaration alone. </Accordion> <Accordion label="Can I change a block's fields after content uses it?" group="faq"> Yes, carefully. Adding optional fields is compatible; amend the active version. Renaming, removing, or retyping a field is breaking: add a new entry to `versions`, keep the old version so stored blocks still render, and update your component to handle both shapes before activating it. The generated `PageContentBlock` union keeps every retained version typed. </Accordion> <Accordion label="Does the theme ever touch my content?" group="faq"> No. The theme is repo code plus `seed/seed.json`. The seed applies once to an empty database; content lives in D1/SQLite and media in R2/disk after that. Redeploying or editing theme files never overwrites entries, and editors' changes never touch your repo. </Accordion> ## Next: ship it You now have the theme surface end to end: tokens and fonts for the look, seed.json for the model, block types for the editor experience, routes and a layout for the wiring, and seeded content for the first-run impression. To see every pattern in this article running in production, browse [emdashhq.com](https://emdashhq.com/), where the blueprint tokens, the custom block types in the page editor, and the single catch-all route are all live. The only thing left is infrastructure: Part 4 deploys this exact stack to Cloudflare Workers, D1, and R2.

--- title: "How to Build a Custom EmDash Theme: Tokens, Blocks, and Seed Schema" description: "Part 3 of the EmDash series: every layer of a custom theme (design tokens, seed.json collections, block types, page routes, menus, widgets, and seeded content) with a real working example." date: 2026-09-30 categories: ["web-development"] tags: ["emdash","astro","themes"] --- import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; This is Part 3 of the EmDash series. [Part 1 reviewed the CMS at 1.0](/emdash-cms-review/) and [Part 2 got a site running locally](/emdash-cms-tutorial/) on Node.js and SQLite. This part is about the layer you actually own: the theme. It covers how an EmDash theme is put together and how to build your own: design tokens, the seed schema, block types, routes, menus, and seeded content. The running example is real: [emdashhq.com](https://emdashhq.com/), the EmDash hub site, started from the stock marketing template and was restyled into a blueprint drawing-sheet look with six custom block types. Deploy is deliberately out of scope; the next part covers Cloudflare Workers, D1, and R2. ![The finished custom theme: emdashhq.com home page with a blueprint grid background, spec-style hero, architecture diagram card, and tutorials index](../../assets/images/26/09/emdash-home.webp)

{value.headline}