Migrer depuis WordPress

Utilisez l’administration d’EmDash pour analyser un site WordPress, préparer des collections compatibles, importer le contenu, copier les médias et réécrire les URL. Gardez le site WordPress disponible tant que le site importé n’a pas passé la vérification.

Avant de commencer

Préparez les éléments suivants :

• Une sauvegarde de la base de données WordPress et de wp-content/uploads.
• Un site EmDash dont le stockage est configuré si vous prévoyez de copier les médias.
• Un compte administrateur EmDash. L’import WordPress nécessite la permission import:execute.
• Soit un export WordPress eXtended RSS (WXR) complet, soit le plugin EmDash Exporter installé sur le site WordPress.

Notez la structure actuelle des permaliens, l’origine canonique, les redirections, les menus, les types de contenu actifs, les taxonomies et tous les champs propres à un plugin que le nouveau site doit conserver.

Choisir une méthode d’importation

Saisir l’URL d’un site sans l’exporteur ne fait qu’interroger l’API REST publique de WordPress. Cette sonde peut détecter WordPress et compter les articles, pages et médias publics, mais elle ne peut pas effectuer d’importation REST directe.

Exporter un fichier WXR

Dans WordPress, ouvrez Tools → Export, sélectionnez All content et téléchargez le fichier d’export XML. Un fichier WXR pointe vers les médias situés sur l’origine WordPress ; il ne contient pas les octets des pièces jointes.

Connecter EmDash Exporter

Dans WordPress, ouvrez Tools → EmDash Migration et générez une clé de migration. Collez la clé dans la page d’importation d’EmDash.

Vous pouvez aussi saisir l’URL du site WordPress. Lorsque l’exporteur est détecté, autorisez EmDash via l’écran des mots de passe d’application de WordPress. Sur les sites de développement locaux en HTTP, saisissez manuellement le nom d’utilisateur WordPress et le mot de passe d’application, car le callback d’autorisation exige HTTPS.

Importer via l’administration

Comportement de la conversion

Statuts

L’importeur fait correspondre les statuts WordPress comme suit :

Les dates planifiées et les règles de visibilité de WordPress ne sont pas reconstituées à partir de ces statuts. Examinez chaque brouillon importé avant de le publier.

Texte enrichi et blocs réutilisables

Le balisage Gutenberg est converti en Portable Text. Le HTML classique est traité par le même convertisseur. Inspectez dans le site EmDash rendu les blocs complexes, les embeds, les shortcodes, le balisage des constructeurs de pages et les blocs définis par des plugins.

Les entrées WXR wp_block sont importées comme sections. Elles ne sont pas importées dans une collection de contenu ordinaire.

Collections et champs

Les correspondances par défaut des types de contenu incluent post vers posts et page vers pages. Les types de contenu personnalisés utilisent un slug de collection nettoyé. L’étape de préparation ajoute les champs standard de titre, de contenu Portable Text, d’extrait et d’image mise en avant dont l’analyse a besoin.

Les champs existants dont les types sont compatibles sont réutilisés. Une incompatibilité de type bloque la correspondance de cette collection ; l’importeur ne convertit pas un champ existant vers un autre type.

Champs personnalisés et données SEO

L’analyse WXR signale les clés de métadonnées d’article non internes et suggère des noms et des types de champs, mais l’import WXR en base de données écrit les champs importés standard au lieu de copier chaque clé de métadonnées arbitraire. Considérez l’analyse comme une liste de contrôle des champs qui peuvent nécessiter une conversion distincte.

Le chemin EmDash Exporter peut copier les métadonnées personnalisées et les valeurs d’Advanced Custom Fields (ACF) lorsque la collection cible possède des champs correspondants. Il peut aussi créer et renseigner les champs pris en charge d’image mise en avant et de SEO Yoast ou Rank Math lorsque leurs options d’import sont activées. Examinez les valeurs PHP sérialisées, les répéteurs, le contenu flexible et les structures propres aux plugins plutôt que de supposer que leur représentation WordPress correspond à un type de champ EmDash.

Auteurs et bylines

Un auteur WordPress associé devient le propriétaire de l’entrée. Les mentions d’auteur affichées utilisent des bylines. S’il n’existe aucune association d’utilisateur, EmDash crée ou réutilise une byline d’invité fondée sur l’identité de l’auteur WordPress.

Taxonomies

Les catégories et les étiquettes sont importées dans les définitions de taxonomie EmDash correspondantes. Le chemin de l’exporteur peut créer des définitions pour les taxonomies personnalisées. Une taxonomie personnalisée WXR sans définition EmDash correspondante est signalée comme manquante et ses affectations sont ignorées.

Médias

La déduplication des médias compare un hachage SHA-1 des octets téléchargés. Une ligne de média existante portant le même hachage est réutilisée. Les noms de fichier et les ID WordPress ne servent pas de clé de déduplication.

Le site source doit rester accessible pendant qu’EmDash télécharge les pièces jointes. Les redirections depuis l’URL d’une pièce jointe sont validées avant d’être suivies.

Relancer une importation partielle

L’import via l’administration est conçu pour ignorer les entrées existantes, mais sa limite de correspondance compte :

• Le contenu existant est mis en correspondance par collection, slug et locale, et non par ID WordPress.
• Si un slug source a changé entre deux tentatives, examinez les deux entrées et résolvez le doublon manuellement.
• Relancer l’étape des médias réutilise les fichiers déjà stockés et identiques octet pour octet, d’après le hachage de leur contenu.
• Le flux de l’exporteur envoie des blocs de taille limitée. Redémarrer le flux dans le navigateur relance les pages de contenu et reconstruit les cartes de relations à partir des entrées ignorées.

L’administration ne conserve pas de fichier de reprise WXR. L’option --resume de emdash import wordpress relève d’un flux CLI distinct qui écrit sur le disque des fichiers JSON convertis ; elle ne reprend pas un import en base de données lancé depuis l’administration.

Vérifier avant la bascule

Comparez le site importé au site source :

• Comptez les entrées par type de contenu et par statut.
• Ouvrez des contenus représentatifs de Gutenberg, de l’éditeur classique, de shortcodes et de constructeurs de pages.
• Vérifiez que les images mises en avant et les médias intégrés se résolvent depuis des URL EmDash.
• Contrôlez les auteurs, les bylines, les catégories, les étiquettes, les taxonomies personnalisées et les traductions.
• Testez les menus, les commentaires, l’identité du site et les champs SEO lorsqu’ils ont été importés via l’exporteur.
• Explorez les anciennes URL publiques et préparez des redirections pour chaque route modifiée.
• Vérifiez que les brouillons restent inaccessibles aux visiteurs non connectés.

Conservez la sauvegarde et le déploiement WordPress jusqu’à ce que le nouveau site ait fonctionné correctement en production et qu’un retour arrière ne soit plus nécessaire.

Dépannage

Le fichier XML ne peut pas être analysé

Exportez de nouveau le fichier depuis Tools → Export et confirmez que le téléchargement s’est terminé. Ne modifiez pas le XML avec un outil qui change son encodage.

Une collection est marquée comme incompatible

Un champ existant a le même slug mais un type différent. Modifiez la correspondance du type de contenu ou conciliez le champ sous Content Types avant de réessayer. L’étape de préparation ajoute les champs manquants mais ne modifie pas les types des champs existants.

Le téléchargement des URL de médias échoue

Vérifiez que la pièce jointe source est accessible sans session WordPress. Les médias protégés par authentification, les fichiers supprimés et les redirections vers des adresses de réseau privé échouent individuellement et restent dans la liste des erreurs de médias.

Adapter le thème

Utilisez getEmDashCollection() pour les routes d’archive et getEmDashEntry() pour une route à slug. entry.id est l’identifiant de la route et correspond normalement au slug ; entry.data.id est l’ID de contenu stocké qu’utilisent les helpers de relations.

La route suivante affiche un article importé :

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

Lisez Porter un thème WordPress pour la correspondance des routes et des composants. Lisez Importation de contenu pour les contrats des points de terminaison et les limites exactes des nouvelles tentatives.