EmDash for WordPress Developers

EmDash brings familiar WordPress concepts—posts, pages, taxonomies, menus, widgets, and a media library—into a modern Astro stack. Your content management knowledge transfers directly.

What Stays Familiar

The concepts you know from WordPress are first-class features in EmDash:

• Collections work like Custom Post Types—define your content structure, query it in templates
• Taxonomies work the same way—hierarchical (like categories) and flat (like tags)
• Menus with drag-and-drop ordering and nested items
• Widget Areas for sidebars and dynamic content regions
• Media library with upload, organization, and image management
• Admin UI that content editors can use without touching code

What’s Different

The implementation changes, but the mental model stays the same:

Quick Reference

Content APIs

Querying Collections

WordPress queries use WP_Query or helper functions. EmDash uses typed query functions.

<?php
$posts = new WP_Query([
  'post_type' => 'post',
  'posts_per_page' => 10,
  'post_status' => 'publish',
  'category_name' => 'news',
]);

while ($posts->have_posts()) :
$posts->the_post();
?>

  <h2><?php the_title(); ?></h2>
  <?php the_excerpt(); ?>
<?php endwhile; ?>

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
status: "published",
limit: 10,
where: { category: "news" },
});

---

{posts.map((post) => (

  <article>
    <h2>{post.data.title}</h2>
    <p>{post.data.excerpt}</p>
  </article>
))}

Getting a Single Entry

<?php
$post = get_post($id);
?>
<article>
  <h1><?php echo $post->post_title; ?></h1>
  <?php echo apply_filters('the_content', $post->post_content); ?>
</article>

---
import { getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

## if (!post) return Astro.redirect("/404");

<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>

Template Hierarchy

WordPress uses a template hierarchy to select which file renders a page. Astro uses explicit file-based routing.

Template Parts → Components

WordPress template parts become Astro components:

// In template:
get_template_part('template-parts/content', 'post');

// template-parts/content-post.php:

<article class="post">
  <h2><?php the_title(); ?></h2>
  <?php the_excerpt(); ?>
</article>

---
const { post } = Astro.props;
---

<article class="post">
	<h2>{post.data.title}</h2>
	<p>{post.data.excerpt}</p>
</article>

---
import PostCard from "../components/PostCard.astro";
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts");
---

{posts.map((post) => <PostCard {post} />)}

Menus

EmDash has first-class menu support with automatic URL resolution:

<?php
wp_nav_menu([
  'theme_location' => 'primary',
  'container' => 'nav',
]);
?>

---
import { getMenu } from "emdash";

## const menu = await getMenu("primary");

<nav>
  <ul>
    {menu?.items.map((item) => (
      <li>
        <a href={item.url}>{item.label}</a>
      </li>
    ))}
  </ul>
</nav>

Menus are created via the admin UI, seed files, or WordPress import.

Widget Areas

Widget areas work like sidebars in WordPress:

<?php if (is_active_sidebar('sidebar-1')) : ?>
  <aside>
    <?php dynamic_sidebar('sidebar-1'); ?>
  </aside>
<?php endif; ?>

---
import { getWidgetArea } from "emdash";
import { PortableText } from "emdash/ui";

## const sidebar = await getWidgetArea("sidebar");

{sidebar && (

  <aside>
    {sidebar.widgets.map((widget) => {
      if (widget.type === "content") {
        return <PortableText value={widget.content} />;
      }
      // Handle other widget types
    })}
  </aside>
)}

Site Settings

Site options and customizer settings map to getSiteSetting():

import { getSiteSetting } from "emdash";

const title = await getSiteSetting("title");
const logo = await getSiteSetting("logo"); // Returns { mediaId, alt, url }

Taxonomies

Taxonomies work the same conceptually—hierarchical (like categories) or flat (like tags):

import { getTaxonomyTerms, getEntryTerms, getTerm } from "emdash";

// Get all categories
const categories = await getTaxonomyTerms("categories");

// Get a specific term
const news = await getTerm("categories", "news");

// Get terms for a post
const postCategories = await getEntryTerms("posts", postId, "categories");

Hooks → Plugin System

WordPress hooks (add_action, add_filter) become EmDash plugin hooks:

What’s Better in EmDash

Preview Links

EmDash generates secure preview URLs with HMAC-signed tokens. Content editors can preview drafts without logging into production—share a link, not credentials.

No Plugin Conflicts

WordPress plugin conflicts disappear. EmDash plugins run in isolated contexts with explicit APIs. No global state pollution.

Content Editor Experience

Content editors use the EmDash admin panel, similar to wp-admin:

• Dashboard with recent activity
• Collection listings with search, filter, and bulk actions
• Rich editor for content (Portable Text, not Gutenberg)
• Media library with drag-and-drop upload
• Menu builder with drag-and-drop ordering
• Widget area editor for sidebar content

The editing experience is familiar. The technology underneath is modern.

Migration Path

EmDash imports WordPress content directly:

1. Export from WordPress (Tools → Export)
2. Upload the .xml file in EmDash’s admin
3. Map post types to collections
4. Import content and media

Posts, pages, taxonomies, menus, and media transfer. Gutenberg blocks convert to Portable Text. Custom fields are analyzed and mapped.

See the WordPress Migration Guide for complete instructions.

Next Steps

• Getting Started — Set up your first EmDash site
• Querying Content — Deep dive into content APIs
• Taxonomies — Categories, tags, and custom taxonomies
• Menus — Navigation menus
• Migrate from WordPress — Import existing content