{"id":97965,"date":"2026-09-30T12:38:00","date_gmt":"2026-09-30T16:38:00","guid":{"rendered":"https:\/\/overcentral.com\/en\/?p=97965"},"modified":"2026-09-29T08:11:20","modified_gmt":"2026-09-29T12:11:20","slug":"custom-emdash-theme-astro-tailwind-97965","status":"publish","type":"post","link":"https:\/\/overcentral.com\/en\/custom-emdash-theme-astro-tailwind-97965\/","title":{"rendered":"How to Build a Custom EmDash Theme Using Astro and Tailwind"},"content":{"rendered":"

EmDash<\/a> is not WordPress. You cannot drop a functions.php<\/code>codecodecodecodecode file into a folder and call it a day. Themes in EmDash are full Astro<\/a> projects with strict boundaries\u2014they never touch the database, never execute arbitrary PHP, and never compromise the sandbox. That changes how you build. Here is the practical approach for developers who already know Astro and Tailwind and want to ship a custom EmDash theme without the guesswork.<\/p>\n

Understanding the EmDash Theme Contract<\/h2>\n

An EmDash theme is an Astro project that lives inside a specific directory structure. It receives content through the EmDash API and renders it using Astro components. The theme has no direct database access. It cannot write files. It cannot execute plugins. This is by design\u2014the plugin sandbox (run via Cloudflare Dynamic Workers) handles all backend logic. Your theme is purely a frontend rendering layer.<\/p>\n

The contract is simple: your theme provides Astro pages and components that query content via the EmDash fetch<\/code>codecodecodecodecode API or using the built-in @emdash-cms\/astro<\/code>codecodecodecodecode integration. That integration exposes content collections, portable text blocks, and media references.<\/p>\n

File Structure That Works<\/h2>\n

EmDash expects a theme to follow Astro conventions with one addition: a emdash.config.ts<\/code>codecodecodecodecode file at the project root. This file declares the theme name, version, and any dependencies. Here is a minimal example:<\/p>\n

“`ts<\/p>\n

\/\/ emdash.config.ts<\/p>\n

import { defineTheme } from ‘@emdash-cms\/astro’;<\/p>\n

export default defineTheme({<\/p>\n

name: ‘my-custom-theme’,<\/p>\n

version: ‘1.0.0’,<\/p>\n

collections: [‘posts’, ‘projects’],<\/p>\n

});<\/p>\n

“`<\/p>\n

The collections<\/code>codecodecodecodecode array tells EmDash which content types your theme will render. If you later add a custom content type in the admin panel, you must update this array\u2014otherwise your theme will not know to query it.<\/p>\n

Inside src\/<\/code>codecodecodecodecode, structure your components by purpose:<\/p>\n

“`<\/p>\n

src\/<\/p>\n

components\/<\/p>\n

Header.astro<\/p>\n

Footer.astro<\/p>\n

PostCard.astro<\/p>\n

layouts\/<\/p>\n

BaseLayout.astro<\/p>\n

pages\/<\/p>\n

index.astro<\/p>\n

posts\/[slug].astro<\/p>\n

styles\/<\/p>\n

global.css<\/p>\n

“`<\/p>\n

EmDash treats src\/pages\/<\/code>codecodecodecodecode as the routing layer. The [slug]<\/code>codecodecodecodecode parameter corresponds to the content item\u2019s slug. You query content inside the Astro frontmatter using the EmDash client.<\/p>\n

Querying Content in Astro Frontmatter<\/h2>\n

EmDash provides a getCollection<\/code>codecodecodecodecode function that works similarly to Astro\u2019s own content collections but connects to the EmDash API. Example for a blog post page:<\/p>\n

“`astro<\/p>\n

\/\/ src\/pages\/posts\/[slug].astro<\/p>\n

import { getCollection } from ‘@emdash-cms\/astro’;<\/p>\n

import BaseLayout from ‘..\/..\/layouts\/BaseLayout.astro’;<\/p>\n

export async function getStaticPaths() {<\/p>\n

const posts = await getCollection(‘posts’);<\/p>\n

return posts.map(post => ({<\/p>\n

params: { slug: post.slug },<\/p>\n

props: { post },<\/p>\n

}));<\/p>\n

}<\/p>\n

const { post } = Astro.props;<\/p>\n

\n

{post.title}<\/h1>\n<\/p>\n<\/article>\n<\/p>\n

“`<\/p>\n

The getCollection<\/code>codecodecodecodecode function handles both SSG and SSR. In SSG mode, it fetches all content at build time. In SSR mode (for dynamic content), it fetches on each request. You control this via the output<\/code>codecodecodecodecode setting in astro.config.mjs<\/code>codecodecodecodecode. For most EmDash sites, you want output: 'hybrid'<\/code>codecodecodecodecode\u2014static for most pages, server-rendered for pages that need live preview or draft content.<\/p>\n

Tailwind Integration Without the Bloat<\/h2>\n

EmDash themes ship with Tailwind support out of the box, but the default configuration includes every utility. For a production theme, prune aggressively.<\/p>\n

Create tailwind.config.ts<\/code>codecodecodecodecode and set content<\/code>codecodecodecodecode to only scan your src\/<\/code>codecodecodecodecode directory:<\/p>\n

“`ts<\/p>\n

export default {<\/p>\n

content: [‘.\/src\/*\/<\/em>.{astro,html,ts,tsx}’],<\/p>\n

theme: {<\/p>\n

extend: {<\/p>\n

colors: {<\/p>\n

primary: ‘#3b82f6’,<\/p>\n

},<\/p>\n

},<\/p>\n

},<\/p>\n

};<\/p>\n

“`<\/p>\n

Then in your BaseLayout.astro<\/code>codecodecodecodecode, import the generated CSS:<\/p>\n

“`astro<\/p>\n

import ‘..\/styles\/global.css’;<\/p>\n

“`<\/p>\n

That global.css<\/code>codecodecodecodecode should contain only the Tailwind directives and any custom base styles:<\/p>\n

“`css<\/p>\n

@tailwind base;<\/p>\n

@tailwind components;<\/p>\n

@tailwind utilities;<\/p>\n

body {<\/p>\n

@apply bg-gray-50 text-gray-900 dark:bg-gray-900 dark:text-gray-100;<\/p>\n

}<\/p>\n

“`<\/p>\n

The non-obvious part: EmDash themes support dark mode through a CSS class on the <\/code>codecodecodecodecode element. The EmDash admin panel toggles this class. Your theme must respond. Use Tailwind\u2019s dark:<\/code>codecodecodecodecode variant and ensure your layout reads the class from the request\u2014Astro\u2019s Astro.request.headers<\/code>codecodecodecodecode gives you the cookie that stores the preference. Alternatively, use @media (prefers-color-scheme: dark)<\/code>codecodecodecodecode if you want system-level detection.<\/p>\n

Handling Portable Text<\/h2>\n

EmDash stores rich content as portable text\u2014a structured JSON format similar to Sanity\u2019s. You cannot just output {post.content}<\/code>codecodecodecodecode. You need a component that renders the blocks.<\/p>\n

EmDash ships a PortableText<\/code>codecodecodecodecode component in @emdash-cms\/astro<\/code>codecodecodecodecode:<\/p>\n

“`astro<\/p>\n

import { PortableText } from ‘@emdash-cms\/astro’;<\/p>\n

import type { PortableTextBlock } from ‘@emdash-cms\/astro’;<\/p>\n

interface Props {<\/p>\n

content: PortableTextBlock[];<\/p>\n

}<\/p>\n

const { content } = Astro.props;<\/p>\n

“`<\/p>\n

By default, it renders standard blocks (paragraph, heading, image, list). To customize a block type, pass a components<\/code>codecodecodecodecode object:<\/p>\n

“`astro<\/p>\n

<PortableText<\/p>\n

content={content}<\/p>\n

components={{<\/p>\n

block: {<\/p>\n

h1: ({ children }) => <\/p>\n

{children}<\/h1>\n

,<\/p>\n

image: ({ value }) => \"{value.alt}\",<\/p>\n

},<\/p>\n

}}<\/p>\n

\/><\/p>\n

“`<\/p>\n

This is where Tailwind shines\u2014you apply utility classes directly in the component map without writing separate CSS.<\/p>\n

Adding Plugin Sandbox Support (Theme Side)<\/h2>\n

Your theme cannot run plugins, but it can interact with them. Plugins expose hooks that your theme can listen to. For example, a plugin that adds a “related posts” section might emit a emdash:related-posts<\/code>codecodecodecodecode event. In your Astro component, you can subscribe:<\/p>\n

“`astro<\/p>\n

import { onEvent } from ‘@emdash-cms\/astro’;<\/p>\n

const relatedPosts = await onEvent(’emdash:related-posts’, { postSlug: post.slug });<\/p>\n

{relatedPosts.length > 0 && (<\/p>\n

\n

Related<\/h2>\n