Migrar un WordPress con años de contenido a Astro no tiene por qué ser una pesadilla, pero tampoco conviene tratarlo como un simple “exportar e importar”. La parte fácil es sacar los posts. La parte delicada está en conservar URLs, imágenes, metadatos, enlaces internos, redirecciones, estructura de contenidos y validación de build sin perder tráfico orgánico por el camino.
El caso es cada vez más habitual: blogs y webs corporativas que nacieron en WordPress, acumularon cientos de entradas, páginas de servicios, ubicaciones, FAQs y landings, pero ya no necesitan PHP, base de datos, panel pesado ni una colección de plugins. Para sitios de contenido principalmente estático, Astro con MDX encaja muy bien: genera HTML, permite trabajar con componentes cuando hace falta y deja el contenido en archivos versionados dentro de un repositorio Git.
La migración no consiste solo en cambiar de tecnología. Es una oportunidad para limpiar estructura, reducir deuda técnica y dejar el contenido en un formato más fácil de revisar, automatizar y mantener.
No todas las migraciones de WordPress a Astro tienen el mismo objetivo. Si se quiere mantener exactamente el mismo diseño y solo servir una versión estática, una herramienta como Simply Static puede ser suficiente. Si se quiere reconstruir el sitio con componentes, layouts nuevos y contenido en Markdown o MDX, el camino razonable es exportar, transformar y validar. Si el equipo de marketing necesita seguir usando WordPress como gestor, entonces tiene sentido estudiar una arquitectura headless.
| Enfoque | Ventajas | Inconvenientes | Cuándo usarlo |
|---|---|---|---|
| Simply Static | Rápido, conserva el HTML generado, reduce PHP en producción | Mantiene WordPress como origen, menos control por componentes | Sitios simples que no necesitan rediseño |
| WordPress headless + Astro | El equipo sigue editando en WordPress, Astro controla el frontend | Más piezas, APIs, caché y sincronización | Equipos que necesitan CMS visual |
| Exportar a Markdown/MDX | Contenido versionado, sin base de datos, build reproducible | Más trabajo inicial, hay que limpiar metadatos | Blogs, documentación y webs de contenido |
| Rehacer a mano | Máximo control | Coste alto si hay cientos de páginas | Sitios pequeños o rediseños completos |
Para un blog con 50 posts, la migración puede resolverse en un día de trabajo concentrado. Para una web de 350 páginas, con 200 artículos, páginas de servicios, ubicaciones y landings de campañas, el enfoque debe ser más metódico. Ahí el sitemap, la estructura de slugs y las pruebas de aceptación importan tanto como el conversor de Markdown.
Antes de tocar WordPress, conviene sacar una foto completa del sitio. El sitemap es el punto de partida, pero no debería ser el único. Hay que revisar URLs indexadas, páginas con tráfico, enlaces internos, taxonomías, imágenes, adjuntos, formularios, redirecciones existentes, shortcodes y cualquier plantilla especial.
Una auditoría mínima debería incluir:
| Elemento | Qué revisar |
| Sitemap XML | Lista principal de URLs a conservar |
| Analytics/Search Console | Páginas con tráfico y consultas relevantes |
| Enlaces internos | Rutas antiguas que deben actualizarse |
| Estructura de permalinks | /postname/, categorías, fechas o slugs personalizados |
| Imágenes | Origen, tamaños, alt text y rutas |
| Shortcodes | Contenido que no se exporta limpio |
| Campos personalizados | ACF, metadatos SEO, autores y taxonomías |
| Formularios | Sustituto en Astro, servicio externo o función serverless |
| Redirecciones | Reglas 301 ya existentes que no deben perderse |
En proyectos grandes es buena idea generar una lista de pruebas: cada URL antigua debe devolver 200 en la nueva web o una redirección 301 correcta. Herramientas como Screaming Frog, scripts propios o tests generados con ayuda de IA pueden ahorrar muchas horas.
WordPress incluye una herramienta de exportación en el panel de administración. Desde Herramientas → Exportar se puede generar un XML con entradas, páginas, categorías, etiquetas y referencias a imágenes. Para un blog sencillo suele bastar.
El problema es que ese XML no contiene todo. No incluye archivos del tema, plugins, lógica de plantillas ni todos los campos personalizados de forma necesariamente cómoda. Por eso, en migraciones serias conviene tener también un backup completo y, si es posible, un volcado de la base de datos.
El XML es útil para convertir contenido. El dump de la base de datos es útil para entender lo que WordPress no muestra con claridad: metadatos de plugins SEO, relaciones, campos personalizados, tipos de contenido, slugs antiguos y datos que pueden perderse en una exportación estándar.
Una herramienta práctica para empezar es wordpress-export-to-markdown. Lee el XML exportado por WordPress y genera archivos Markdown con frontmatter básico. También puede descargar imágenes desde el sitio original, por lo que conviene mantener WordPress accesible durante la conversión.
El flujo típico sería:
npx wordpress-export-to-markdownLenguaje del código: JavaScript (javascript)El resultado inicial suele parecerse a esto:
---
title: "Título del artículo"
date: "2023-05-15"
---
Contenido del artículo con imágenes:
Lenguaje del código: JavaScript (javascript)Ese output es solo el comienzo. Para que encaje bien en Astro, normalmente habrá que añadir descripción, tags, categorías, autor, imagen destacada, slug, canonical, fecha en formato correcto y cualquier campo que exija la colección de contenido.
Astro permite trabajar con colecciones de contenido y validar el frontmatter con Zod. Esto es muy útil porque convierte errores silenciosos en fallos de build. Si una entrada no tiene fecha válida, una imagen apunta mal o un campo no cumple el tipo esperado, el build lo dice.
Un ejemplo sencillo de colección:
import { defineCollection, z } from "astro:content";
const posts = defineCollection({
schema: ({ image }) =>
z.object({
date: z.date(),
title: z.string(),
description: z.string().optional(),
image: image().optional(),
categories: z.array(z.string()).optional(),
authors: z.array(z.string()).optional(),
tags: z.array(z.string()).optional(),
canonical: z.string().optional(),
}),
});
export const collections = { posts };Lenguaje del código: JavaScript (javascript)La recomendación es definir este schema antes de convertir cientos de archivos. Así la IA, los scripts o las transformaciones masivas trabajan hacia una estructura clara, no hacia un formato improvisado.
Codex CLI, Claude Code u otros agentes de programación pueden ayudar mucho en esta parte. No deberían sustituir la revisión técnica, pero sí quitar de encima trabajo mecánico: convertir imágenes, actualizar rutas, generar frontmatter, detectar HTML roto, adaptar shortcodes, crear layouts y corregir errores de build.
Tareas donde la IA suele aportar valor:
| Tarea | Qué puede hacer el agente |
| Normalizar frontmatter | Añadir campos exigidos por Astro |
| Convertir imágenes | Pasar PNG/JPEG a WebP o AVIF |
| Actualizar referencias | Cambiar rutas en Markdown/MDX |
| Limpiar HTML de WordPress | Cerrar etiquetas, escapar caracteres, quitar basura |
| Adaptar plantillas | Convertir PHP repetitivo a componentes Astro |
| Revisar errores de build | Leer el log y proponer cambios |
| Crear tests de URLs | Comparar sitemap antiguo y nuevo |
| Generar redirecciones | Crear CSV o reglas para Cloudflare/Nginx |
Un ejemplo de conversión de imágenes:
for img in images/*.{png,jpg,jpeg}; do
cwebp -q 80 "$img" -o "${img%.*}.webp"
doneDespués hay que actualizar las referencias:
<!-- Antes -->
<!-- Después -->
Lenguaje del código: HTML, XML (xml)En Astro suele ser mejor guardar imágenes locales dentro de src/ cuando se quiere que Astro las procese. Los archivos en public/ se sirven tal cual, sin transformación. Para contenido migrado, una estructura ordenada ayuda mucho:
src/
content/
posts/
mi-articulo.mdx
assets/
images/
mi-articulo/
featured.webp
screenshot-1.webpSi el WordPress antiguo usaba una estructura limpia como /%postname%/, conservar URLs en Astro es relativamente sencillo: basta con generar rutas o archivos que respeten el slug. Si había estructuras con categorías, fechas, IDs o slugs históricos, puede hacer falta una capa de redirecciones.
La obsesión por evitar cualquier 301 no siempre compensa. Si la nueva arquitectura mejora mucho la estructura del sitio, una redirección bien hecha es preferible a arrastrar URLs malas durante años. Lo importante es que no haya 404, cadenas de redirección innecesarias ni cambios masivos sin control.
| Situación | Recomendación |
| Slug limpio y útil | Mantener URL |
| URL antigua con fecha irrelevante | Valorar redirección a una ruta mejor |
| Landing de campañas activa | Mantener exactamente la URL |
| Página sin tráfico ni enlaces | Redirigir o consolidar |
| Categorías antiguas mal organizadas | Revisar arquitectura antes de copiar |
| Cambio de dominio | 301 desde el dominio anterior al nuevo |
En Cloudflare se pueden usar Bulk Redirects para grandes lotes de redirecciones. En Nginx o Apache también se pueden crear reglas a nivel de servidor. Lo importante es probarlas con una lista real de URLs antes de apagar WordPress.
La migración no termina cuando los archivos MDX están en src/content/posts/. Termina cuando el build pasa, las URLs responden, las imágenes cargan, los enlaces internos apuntan al nuevo sitio y Search Console no empieza a llenarse de errores.
Un flujo razonable:
bun run buildo, si se usa npm:
npm run buildErrores frecuentes:
| Error | Causa habitual |
| Imagen no encontrada | Ruta mal convertida o archivo movido |
| Frontmatter inválido | Fecha, array o campo requerido mal formado |
| MDX rompe el build | HTML sin cerrar, caracteres sin escapar, componentes sin importar |
| Enlaces viejos | URLs absolutas del dominio anterior |
| Shortcodes visibles | Contenido de WordPress no transformado |
| Slugs duplicados | Posts y páginas con la misma ruta |
| Redirecciones incorrectas | Reglas incompletas o mal ordenadas |
La mejor práctica es construir después de cada lote de cambios, no al final. Si se transforman 300 archivos y se ejecuta el build por primera vez después, depurar será mucho más lento.
Astro puede desplegarse en Cloudflare Pages, Netlify, Vercel, GitHub Pages o un VPS. Para un sitio estático, el despliegue desde Git es cómodo: cada merge dispara un build y deja una versión reproducible.
Después del despliegue toca mirar lo aburrido, que suele ser lo importante: logs, 404, Search Console, sitemap nuevo, robots.txt, canónicas, redirecciones, tiempo de carga, imágenes pesadas y páginas que perdieron tráfico. Durante unos días, no conviene borrar el WordPress original. Es mejor dejarlo accesible en privado o con backup listo por si aparece contenido perdido.
Migrar WordPress a Astro y MDX no es solo ganar velocidad. Es pasar de un sitio dependiente de base de datos, plugins y panel de administración a un proyecto versionado, validado y más fácil de automatizar. Para blogs técnicos, documentación y webs de servicios con mucho contenido, el cambio puede merecer mucho la pena.
La clave está en no saltarse el trabajo previo. Exportar es fácil. Migrar bien exige inventario, schema, pruebas, imágenes ordenadas, redirecciones y revisión. Con buenas herramientas y agentes de IA para las tareas repetitivas, el proceso deja de ser artesanal y se convierte en una migración controlada.
¿Cuánto tarda migrar WordPress a Astro?
Depende del volumen y la complejidad. Un blog de 50 artículos puede migrarse en un día. Una web de 350 páginas necesita inventario, pruebas y revisión, así que puede requerir varios días o semanas.
¿Es mejor Simply Static o convertir a MDX?
Simply Static es más rápido si solo se quiere servir el HTML actual. MDX es mejor si se quiere limpiar contenido, usar componentes Astro y dejar el sitio mantenible en Git.
¿Hay que conservar todas las URLs antiguas?
Conviene conservar las URLs con tráfico, enlaces o campañas activas. Las rutas malas pueden redirigirse con 301 si la nueva estructura mejora el sitio.
¿Puedo usar IA para migrar todo automáticamente?
Puede ayudar mucho con tareas repetitivas, pero siempre debe haber revisión. La IA puede mover imágenes, generar frontmatter y corregir errores de build, pero también puede romper rutas o inventar metadatos.
