EmDash para Desenvolvedores WordPress

O EmDash traz conceitos familiares do WordPress—posts, páginas, taxonomias, menus, widgets e uma biblioteca de mídia—para uma stack moderna do Astro. Seu conhecimento de gerenciamento de conteúdo é transferido diretamente.

Se você está comparando plataformas antes de migrar, leia EmDash vs WordPress e WordPress para Astro com EmDash.

O Que Permanece Familiar

Os conceitos que você conhece do WordPress são recursos de primeira classe no EmDash:

• Coleções funcionam como Tipos de Post Personalizados—defina a estrutura do seu conteúdo, consulte-a em templates
• Taxonomias funcionam da mesma forma—hierárquicas (como categorias) e planas (como tags)
• Menus com ordenação por arrastar e soltar e itens aninhados
• Áreas de Widget para barras laterais e regiões de conteúdo dinâmico
• Biblioteca de mídia com upload, organização e gerenciamento de imagens
• Interface de administração que editores de conteúdo podem usar sem tocar em código

Dica

Você não precisa saber React ou qualquer framework JavaScript específico. Componentes Astro usam HTML com expressões de template simples—mais próximas de templates PHP do que de React.

O Que é Diferente

A implementação muda, mas o modelo mental permanece o mesmo:

TypeScript em vez de PHP

Templates são componentes Astro. A sintaxe é mais limpa, mas o conceito é o mesmo: código do servidor que gera HTML.

APIs de conteúdo em vez de WP_Query

Funções de consulta como getEmDashCollection() substituem WP_Query. Sem SQL, apenas chamadas de função.

Roteamento baseado em arquivos

Arquivos em src/pages/ se tornam URLs. Sem regras de reescrita ou hierarquia de templates para memorizar.

Componentes em vez de partes de template

Importe e use componentes. Mesma ideia que get_template_part(), melhor organização.

Referência Rápida

WordPress	EmDash	Notas
Tipos de Post Personalizados	Coleções	Defina via UI de administração ou API
WP_Query	getEmDashCollection()	Filtros, limites, consultas de taxonomia
get_post()	getEmDashEntry()	Retorna entrada ou nulo
Categorias/Tags	Taxonomias	Suporte hierárquico preservado
register_nav_menus()	getMenu()	Suporte de menu de primeira classe
register_sidebar()	getWidgetArea()	Áreas de widget de primeira classe
bloginfo('name')	getSiteSetting("title")	API de configurações do site
the_content()	<PortableText />	Renderização de conteúdo estruturado
Shortcodes	Blocos de Texto Portátil	Componentes personalizados
add_action/filter()	Ganchos de plugin	content:beforeSave, etc.
wp_options	ctx.kv	Armazenamento chave-valor
Diretório do tema	Diretório src/	Componentes, layouts, páginas
functions.php	astro.config.mjs + configuração do EmDash	Configuração de build e runtime

APIs de Conteúdo

Consultando Coleções

Consultas no WordPress usam WP_Query ou funções auxiliares. O EmDash usa funções de consulta tipadas.

WordPress

archive.php

<?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; ?>

EmDash

astro title="src/pages/posts/index.astro"
---
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>
))}

Obtendo uma Única Entrada

WordPress

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

EmDash

astro title="src/pages/posts/[slug].astro"
---
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>

Hierarquia de Templates

O WordPress usa uma hierarquia de templates para selecionar qual arquivo renderiza uma página. O Astro usa roteamento explícito baseado em arquivos.

Template WordPress	Equivalente no EmDash
index.php	src/pages/index.astro
single.php	src/pages/posts/[slug].astro
single-{type}.php	src/pages/{type}/[slug].astro
page.php	src/pages/pages/[slug].astro
archive.php	src/pages/posts/index.astro
archive-{type}.php	src/pages/{type}/index.astro
category.php	src/pages/categories/[slug].astro
tag.php	src/pages/tags/[slug].astro
search.php	src/pages/search.astro
404.php	src/pages/404.astro
header.php / footer.php	src/layouts/Base.astro
sidebar.php	src/components/Sidebar.astro

Dica

O roteamento do Astro é mais explícito que a hierarquia do WordPress. Cada rota é um arquivo. Segmentos dinâmicos usam a sintaxe [param].

Partes de Template → Componentes

Partes de template do WordPress se tornam componentes Astro:

WordPress

php title="functions.php / template"
// No 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>

EmDash

astro title="src/components/PostCard.astro"
---
const { post } = Astro.props;
---

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

astro title="src/pages/index.astro"
---
import PostCard from "../../components/PostCard.astro";
import { getEmDashCollection } from "emdash";

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

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

Menus

O EmDash possui suporte de primeira classe para menus com resolução automática de URLs:

WordPress

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

EmDash

astro title="src/components/Header.astro"
---
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>

Os menus são criados através da interface administrativa, arquivos de seed ou importação do WordPress.

Áreas de Widgets

As áreas de widgets funcionam como sidebars no WordPress:

WordPress

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

EmDash

astro title="src/components/Sidebar.astro"
---
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} />;
      }
      // Lidar com outros tipos de widget
    })}
  </aside>
)}

Configurações do Site

As opções do site e configurações do personalizador mapeiam para getSiteSetting():

WordPress	EmDash
bloginfo('name')	getSiteSetting("title")
bloginfo('description')	getSiteSetting("tagline")
get_custom_logo()	getSiteSetting("logo")
get_option('date_format')	getSiteSetting("dateFormat")
home_url()	Astro.site

import { getSiteSetting } from "emdash";

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

Taxonomias

As taxonomias funcionam conceitualmente da mesma forma — hierárquicas (como categorias) ou planas (como tags):

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

// Obter todas as categorias
const categories = await getTaxonomyTerms("categories");

// Obter um termo específico
const news = await getTerm("categories", "news");

// Obter termos para um post
const postCategories = await getEntryTerms("posts", postId, "categories");

Hooks → Sistema de Plugins

Os hooks do WordPress (add_action, add_filter) tornam-se hooks de plugins do EmDash:

WordPress Hook	EmDash Hook	Propósito
save_post	content:beforeSave	Modificar conteúdo antes de salvar
the_content	PortableText components	Transformar conteúdo renderizado
pre_get_posts	Query options	Filtrar consultas
wp_head	Layout <head>	Adicionar conteúdo ao head
wp_footer	Layout before </body>	Adicionar conteúdo ao rodapé

O que é Melhor no EmDash

Type Safety

TypeScript em toda parte. Coleções, consultas e componentes são totalmente tipados. Chega de adivinhar nomes de campos ou tipos de retorno.

Performance

Sem sobrecarga de PHP. Geração estática por padrão. Renderização no servidor quando necessário. Pronto para implantação na edge.

Modern DX

Substituição de módulos a quente. Arquitetura baseada em componentes. Ferramentas modernas (Vite, TypeScript, ESLint).

Git-based Deployments

Código e templates no git. Conteúdo no banco de dados. Sem FTP, sem permissões de arquivo, sem sites hackeados.

Links de Pré-visualização

O EmDash gera URLs de pré-visualização seguras com tokens assinados por HMAC. Editores de conteúdo podem pré-visualizar rascunhos sem fazer login na produção — compartilhe um link, não credenciais.

Sem Conflitos de Plugins

Os conflitos de plugins do WordPress desaparecem. Os plugins do EmDash são executados em contextos isolados com APIs explícitas. Sem poluição de estado global.

Experiência do Editor de Conteúdo

Os editores de conteúdo usam o painel administrativo do EmDash, semelhante ao wp-admin:

• Dashboard com atividade recente
• Listagens de coleções com busca, filtro e ações em massa
• Editor rico para conteúdo (Portable Text, não Gutenberg)
• Biblioteca de mídia com upload por arrastar e soltar
• Construtor de menus com ordenação por arrastar e soltar
• Editor de áreas de widgets para conteúdo de sidebar

A experiência de edição é familiar. A tecnologia por trás é moderna.

Caminho de Migração

O EmDash importa conteúdo do WordPress diretamente:

1. Exporte do WordPress (Ferramentas → Exportar)
2. Faça upload do arquivo .xml no admin do EmDash
3. Mapeie tipos de post para coleções
4. Importe conteúdo e mídia

Posts, páginas, taxonomias, menus e mídia são transferidos. Blocos do Gutenberg são convertidos para Portable Text. Campos personalizados são analisados e mapeados.

Consulte o Guia de Migração do WordPress para instruções completas.

Próximos Passos

• Começando — Configure seu primeiro site EmDash
• Consultando Conteúdo — Mergulhe fundo nas APIs de conteúdo
• Taxonomias — Categorias, tags e taxonomias personalizadas
• Menus — Menus de navegação
• Migrar do WordPress — Importe conteúdo existente