Migrar do WordPress

Use o administrador do EmDash para analisar um site WordPress, preparar coleções compatíveis, importar conteúdo, copiar mídia e reescrever URLs. Mantenha o site WordPress disponível até que o site importado tenha passado na verificação.

Antes de começar

Prepare os seguintes itens:

• Um backup do banco de dados do WordPress e de wp-content/uploads.
• Um site EmDash com o armazenamento configurado, caso pretenda copiar mídia.
• Uma conta de administrador do EmDash. A importação do WordPress exige a permissão import:execute.
• Uma exportação completa do WordPress eXtended RSS (WXR) ou o plugin EmDash Exporter instalado no site WordPress.

Registre a estrutura atual de links permanentes, a origem canônica, os redirecionamentos, os menus, os tipos de post ativos, as taxonomias e quaisquer campos pertencentes a plugins que o novo site precise preservar.

Escolher um método de importação

Informar a URL de um site sem o exporter apenas sonda a API REST pública do WordPress. A sondagem consegue detectar o WordPress e contar posts, páginas e mídia públicos, mas não consegue realizar uma importação REST direta.

Exportar um arquivo WXR

No WordPress, abra Tools → Export, selecione All content e baixe o arquivo de exportação XML. Um arquivo WXR aponta para a mídia na origem do WordPress; ele não contém os bytes dos anexos.

Conectar o EmDash Exporter

No WordPress, abra Tools → EmDash Migration e gere uma chave de migração. Cole a chave na página de importação do EmDash.

Você também pode informar a URL do site WordPress. Quando o exporter for detectado, autorize o EmDash pela tela de senhas de aplicativo do WordPress. Em sites de desenvolvimento locais com HTTP, informe manualmente o nome de usuário do WordPress e a senha de aplicativo, pois o callback de autorização exige HTTPS.

Importar pelo administrador

Comportamento da conversão

Status

O importador associa os status do WordPress da seguinte forma:

As datas agendadas e as regras de visibilidade do WordPress não são reconstruídas a partir desses status. Revise cada rascunho importado antes da publicação.

Rich text e blocos reutilizáveis

A marcação do Gutenberg é convertida em Portable Text. O HTML clássico é processado pelo mesmo conversor. Inspecione no site EmDash renderizado os blocos complexos, os embeds, os shortcodes, a marcação de page builders e os blocos definidos por plugins.

As entradas wp_block do WXR são importadas como sections. Elas não são importadas para uma coleção de conteúdo comum.

Coleções e campos

As associações padrão de tipos de post incluem post para posts e page para pages. Os tipos de post personalizados usam um slug de coleção higienizado. A etapa de preparação adiciona os campos padrão de título, conteúdo em Portable Text, resumo e imagem destacada de que a análise precisa.

Os campos existentes com tipos compatíveis são reutilizados. Uma incompatibilidade de tipo bloqueia a associação dessa coleção; o importador não força a conversão de um campo existente para outro tipo.

Campos personalizados e dados de SEO

A análise do WXR informa as chaves de post-meta não internas e sugere nomes e tipos de campo, mas a importação do WXR para o banco de dados grava os campos padrão importados em vez de copiar cada chave meta arbitrária. Trate a análise como uma lista de verificação de campos que podem precisar de uma conversão separada.

O caminho do EmDash Exporter pode copiar os metadados personalizados e os valores do Advanced Custom Fields (ACF) quando a coleção de destino tem campos correspondentes. Ele também pode criar e preencher os campos compatíveis de imagem destacada e de SEO do Yoast ou do Rank Math quando as opções de importação correspondentes estão ativadas. Revise valores PHP serializados, repeaters, conteúdo flexível e estruturas específicas de plugins em vez de presumir que a representação deles no WordPress corresponde a um tipo de campo do EmDash.

Autores e bylines

Um autor do WordPress associado passa a ser o proprietário da entrada. Os créditos exibidos usam bylines. Se não houver associação de usuário, o EmDash cria ou reutiliza um byline de convidado com base na identidade do autor no WordPress.

Taxonomias

Categorias e tags são importadas para as definições de taxonomia correspondentes do EmDash. O caminho do exporter pode criar definições para taxonomias personalizadas. Uma taxonomia personalizada do WXR sem uma definição correspondente no EmDash é informada como ausente e suas atribuições são ignoradas.

Mídia

A deduplicação de mídia compara um hash SHA-1 dos bytes baixados. Uma linha de mídia existente com o mesmo hash é reutilizada. Nomes de arquivo e IDs do WordPress não são a chave de deduplicação.

O site de origem precisa continuar acessível enquanto o EmDash baixa os anexos. Os redirecionamentos a partir da URL de um anexo são validados antes de serem seguidos.

Tentar novamente uma importação parcial

A importação pelo administrador foi projetada para ignorar entradas existentes, mas o limite do critério de correspondência é importante:

• O conteúdo existente é correspondido por coleção, slug e localidade, não por ID do WordPress.
• Se um slug de origem mudou entre as tentativas, inspecione as duas entradas e resolva a duplicata manualmente.
• Executar novamente a etapa de mídia reutiliza, pelo hash do conteúdo, os arquivos já armazenados e idênticos byte a byte.
• O fluxo do exporter envia blocos de tamanho limitado. Reiniciar o fluxo no navegador executa novamente as páginas de conteúdo e reconstrói os mapas de relacionamentos a partir das entradas ignoradas.

O administrador não persiste um arquivo de retomada do WXR. A flag --resume de emdash import wordpress pertence a um fluxo de CLI separado que grava arquivos JSON convertidos em disco; ela não retoma uma importação para o banco de dados feita pelo administrador.

Verificar antes da virada

Confira o site importado em relação à origem:

• Conte as entradas por tipo de post e status.
• Abra conteúdo representativo do Gutenberg, do Editor Clássico, de shortcodes e de page builders.
• Confirme que as imagens destacadas e a mídia embutida são resolvidas a partir de URLs do EmDash.
• Verifique autores, bylines, categorias, tags, taxonomias personalizadas e traduções.
• Teste menus, comentários, identidade do site e campos de SEO quando importados pelo exporter.
• Rastreie as URLs públicas antigas e prepare redirecionamentos para cada rota alterada.
• Verifique se os rascunhos continuam inacessíveis para visitantes sem login.

Mantenha o backup e a implantação do WordPress até que o novo site tenha funcionado com sucesso em produção e um rollback não seja mais necessário.

Solução de problemas

Não é possível analisar o arquivo XML

Exporte o arquivo novamente em Tools → Export e confirme que o download foi concluído. Não edite o XML com uma ferramenta que altere a codificação.

Uma coleção é marcada como incompatível

Um campo existente tem o mesmo slug, mas um tipo diferente. Altere a associação do tipo de post ou concilie o campo em Content Types antes de tentar novamente. A etapa de preparação adiciona os campos que faltam, mas não altera os tipos dos campos existentes.

O download das URLs de mídia falha

Verifique se o anexo de origem está acessível sem uma sessão do WordPress. Mídia protegida por autenticação, arquivos removidos e redirecionamentos para endereços de rede privada falham individualmente e permanecem na lista de erros de mídia.

Adaptar o tema

Use getEmDashCollection() para as rotas de arquivo e getEmDashEntry() para uma rota de slug. entry.id é o identificador da rota e normalmente é o slug; entry.data.id é o ID de conteúdo armazenado usado pelos helpers de relacionamento.

A rota a seguir renderiza um post importado:

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

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Could not load the post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

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

Leia Portar um tema WordPress para o mapeamento de rotas e componentes. Leia Importação de Conteúdo para os contratos dos endpoints e os limites exatos das novas tentativas.