Migrer un blog WordPress vers Ghost n'est pas un simple export/import. Les différences de format, de structure de contenu et de gestion des médias nécessitent une approche méthodique. Voici la méthode que nous utilisons en production.

Étape 1 : Export WordPress

WordPress exporte au format WXR (WordPress eXtended RSS), un fichier XML qui contient :

  • Les articles avec leur contenu HTML (et les commentaires Gutenberg)
  • Les pages
  • Les catégories et tags
  • Les métadonnées SEO (si Yoast ou RankMath sont installés)
  • Les références aux médias (mais pas les fichiers eux-mêmes)

Allez dans Outils > Exporter > Tous les contenus pour générer le fichier.

Étape 2 : Nettoyage du HTML

Le contenu WordPress exporté contient des commentaires Gutenberg qu'il faut supprimer :

<!-- wp:paragraph -->
<p>Votre texte ici</p>
<!-- /wp:paragraph -->

Ces commentaires sont inutiles dans Ghost et polluent le contenu. Un simple regex les élimine :

import re
content = re.sub(r'<!-- /?wp:\w+[^>]*?-->\n?', '', content)

Étape 3 : Migration des tags

Ghost utilise des tags (pas de catégories). La stratégie recommandée :

  • Convertir les catégories WordPress en tags Ghost
  • Conserver les tags WordPress comme tags Ghost supplémentaires
  • Définir le primary_tag comme l'ancienne catégorie principale

Étape 4 : Migration des images

Les images WordPress sont référencées par URL dans le contenu HTML. Deux approches :

  1. Conserver les URLs : si WordPress reste accessible, les images continueront de fonctionner. Solution rapide mais fragile.
  2. Migrer les images : télécharger chaque image et la réuploader via l'API Ghost. Solution robuste mais plus complexe.

Nous recommandons l'approche 2 pour la pérennité. L'API Ghost Admin permet l'upload d'images en multipart/form-data.

Étape 5 : Import via l'API Admin

Ghost expose une API Admin complète. Pour chaque article :

  1. Créer les tags (s'ils n'existent pas déjà)
  2. Uploader l'image à la une
  3. Créer le post avec le contenu au format mobiledoc (HTML card)
  4. Ajouter les métadonnées SEO

Le format mobiledoc pour injecter du HTML brut :

{
  "version": "0.3.1",
  "cards": [["html", {"html": "votre contenu HTML"}]],
  "sections": [[10, 0]]
}

Pièges courants

  • Encodage : les entités HTML (&amp;, &nbsp;) doivent être correctement gérées
  • Slugs : WordPress peut générer des slugs numériques (comme "36-2") — regénérez-les depuis le titre
  • Dates : conservez les dates de publication originales pour le SEO
  • Redirections : si les URLs changent, configurez des redirections 301
  • Ghost 5 et Lexical : Ghost 5 utilise le format Lexical par défaut. Envoyez le contenu en mobiledoc et mettez lexical: null pour forcer la conversion

Conclusion

La migration WordPress → Ghost est un processus technique mais prévisible. Avec une approche scriptée (Python + Ghost Admin API), vous pouvez migrer des centaines d'articles en quelques minutes tout en préservant le contenu, les métadonnées et les images.