Como Migre Mi Sitio WordPress a Astro y MDX

Tenia un blog de WordPress en wpdoze.com con un monton de articulos antiguos que queria mover a bitdoze.com, que se ejecuta en Astro con MDX. Segui posponiendolo porque supuse que seria doloroso. Resulta que no fue tan mal, y quiero compartir lo que hice para que te saltes la parte de prueba y error.

Por que deje WordPress

Mira, WordPress funciona. Millones de sitios se ejecutan en el por buena razon. Pero mi sitio era solo articulos estaticos, y todavia estaba pagando por hosting, cuidando actualizaciones de plugins y viendo los tiempos de carga de pagina empeorar. Astro genera archivos HTML planos, asi que las paginas cargan instantaneamente sin base de datos o PHP involucrado. Alojar en Cloudflare Pages cuesta cero dolares. Y puedo escribir en archivos MDX en un repositorio Git en lugar de pelear con el editor de bloques. Eso fue suficiente para mi.

Como fue la migracion

La version corta:

1. Exporte todo de WordPress (posts, paginas, imagenes)
2. Convierti la exportacion XML a archivos Markdown
3. Use Codex CLI de OpenAI para automatizar las partes aburridas: conversion de imagenes, formateo de frontmatter, arreglando referencias de imagen
4. Construi el proyecto Astro y arregle lo que se rompio
5. Redirigi el dominio antiguo al nuevo

Recorrere cada paso.

Paso 1: Exportar tu contenido de WordPress

WordPress tiene una herramienta de exportacion integrada. Ve a Tools → Export en tu panel de admin y exporta All content. Obtienes un archivo XML con todos tus posts, paginas, categorias, etiquetas y referencias de imagen.

Algunas cosas que vale la pena saber:

• La exportacion tiene URLs de imagenes pero no los archivos reales. El conversor en el siguiente paso los descarga por ti.
• Tipos de posts personalizados o campos ACF podrian necesitar manejo extra. Para un blog regular, la exportacion predeterminada es suficiente.
• Respaldar tu sitio primero. Probablemente no necesitaras el respaldo, pero dormiras mejor.

Paso 2: Convertir WordPress XML a Markdown

wordpress-export-to-markdown es una herramienta Node.js que lee tu exportacion XML y escupe archivos Markdown con frontmatter. Tambien descarga todas las imagenes.

Instalar y ejecutar

npx wordpress-export-to-markdown

La herramienta te guia a traves de una configuracion interactiva: donde esta el archivo XML, donde poner la salida, como manejar imagenes. Guarde imagenes, salte carpetas de ano/mes (queria una estructura plana para reorganizar despues) y exclui borradores.

Cuando termina, tienes una carpeta de archivos .md y un directorio con todas las imagenes.

Como se ve la salida

Cada post se convierte en un archivo Markdown con frontmatter basico:

---
title: "Tu Titulo del Post"
date: "2023-05-15"
---

Tu contenido del post aqui con imagenes referenciadas como:
![alt text](images/tu-imagen.png)

El frontmatter es basico. Todavia necesitas agregar campos que tu coleccion de contenido de Astro espera (description, categories, tags, canonical URL, etc.). Ahi es donde entro Codex CLI.

Paso 3: Dejar que la IA maneje el trabajo pesado

Este paso me ahorro horas. Use Codex CLI de OpenAI para manejar los cambios repetitivos archivo por archivo que no iba a hacer a mano para mas de 50 articulos.

Convertir imagenes a WebP

La exportacion de WordPress tenia una mezcla de archivos PNG y JPEG, muchos de ellos sobredimensionados. Tuve a Codex CLI convertir por lotes todo a WebP:

# Codex CLI manejo la conversion por lotes
# Convirtiendo todas las imagenes PNG/JPEG a formato WebP
for img in images/*.{png,jpg,jpeg}; do
  cwebp -q 80 "$img" -o "${img%.*}.webp"
done

Los archivos WebP corren aproximadamente 25-35% mas pequenos que JPEGs equivalentes a calidad similar. A traves de todo un blog, eso es mucho ancho de banda ahorrado.

Actualizar referencias de imagen

Despues de convertir imagenes, todos los archivos Markdown todavia apuntaban a nombres de archivo .png y .jpg. Codex CLI paso por cada archivo y cambio las extensiones:

<!-- Antes -->
![screenshot](images/dashboard-screenshot.png)

<!-- Despues -->
![screenshot](images/dashboard-screenshot.webp)

Formatear frontmatter para Astro

Mi sitio Astro usa un esquema de frontmatter validado por Zod. Los archivos exportados tenian casi nada en el frontmatter, asi que Codex CLI reformateo cada uno para coincidir:

---
date: 2023-05-15T00:00:00Z
title: "Tu Titulo del Post"
description: "Una breve descripcion extraida del primer parrafo"
image: "../../assets/images/tu-post/featured.webp"
categories: ["cms"]
authors: ["Dragos"]
tags: ["wordpress", "tutoriales"]
canonical: "https://www.bitdoze.com/tu-post-slug/"
---

Mover imagenes al lugar correcto

Astro optimiza imagenes mejor cuando viven en src/assets/ en lugar de public/. Codex CLI movio las imagenes de cada post a la estructura de directorio correcta:

src/assets/images/
  └── post-slug/
      ├── featured.webp
      └── screenshot-1.webp

Paso 4: Configurar tu coleccion de contenido de Astro

Si no tienes un sitio Astro aun, ve configura uno primero. Mi guia de blog Astro gratuito cubre eso.

Tu configuracion de coleccion de contenido (src/content/config.ts) define que campos necesitan tus posts:

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

Pon tus archivos MDX convertidos en src/content/posts/ e imagenes en src/assets/images/.

Paso 5: Construir y arreglar lo que se rompe

Ejecuta tu construccion de Astro para ver que esta roto:

bun run build

Cosas que me tropezaron:

• Rutas de imagen rotas donde la referencia en el archivo MDX no coincidia con la ubicacion real del archivo
• Frontmatter invalido que la validacion Zod de Astro rechazo (te dice exactamente que campo en que archivo, lo cual es bonito)
• HTML de WordPress que a MDX no le gusto, mayormente etiquetas sin cerrar y caracteres especiales sin escapar
• Imports de componentes faltantes en la parte superior de archivos MDX

Ejecute la construccion despues de cada lote de cambios, asi que cuando algo se rompia sabia lo que acababa de tocar. Codex CLI tambien ayudo aqui leyendo la salida de error de construccion y arreglando los problemas automaticamente.

Paso 6: Desplegar y redirigir

Una vez que la construccion pasa, despliega. Yo uso Cloudflare Pages y escribi una guia sobre desplegar Astro a Cloudflare si esa es tu configuracion tambien. Tambien puedes desplegar Astro en un VPS si prefieres gestionar tu propio servidor.

Configurar redirecciones de dominio

La ultima pieza: redirigir tu dominio antiguo. Apunte wpdoze.com a bitdoze.com. Como haces esto depende de tu configuracion DNS:

• En Cloudflare, usa Page Rules o Bulk Redirects para hacer 301 del dominio antiguo al nuevo.
• Con otros proveedores, configura un 301 a nivel de servidor o usa el reenvio de URL de tu registrador.

# Ejemplo de Cloudflare Page Rule
wpdoze.com/* → https://www.bitdoze.com/$1 (redireccion 301)

Cosas que desearia haber sabido antes

Algunas cosas que aprendi en el camino:

Despues de la migracion

Una vez que tu contenido este arriba, algunas cosas valen la pena hacer:

• Escribi una guia sobre optimizacion de construccion SSG de Astro porque sitios grandes pueden volverse lentos de construir. Vale la pena leerlo si tienes mas de un punado de posts.
• Si estas en Node.js, cambiar a Bun redujo mis tiempos de construccion notablemente.
• Probablemente queras un formulario de contacto en algun momento.
• Para analiticas, uso Plausible enmascarado a traves de Cloudflare Workers. Escribi como configurar eso.

Preguntas frecuentes

¿Cuanto tiempo toma toda la migracion?

Depende de cuantos posts tengas. Mi sitio tenia alrededor de 50 articulos y todo tomo aproximadamente un dia. La mayor parte de ese tiempo fue revisar lo que Codex CLI produjo y arreglar casos borde. La exportacion y conversion real fue tal vez una hora.

¿Necesito saber TypeScript para usar Astro?

No. JavaScript plano funciona bien en componentes Astro. TypeScript es opcional, aunque lo recomiendo para esquemas de coleccion de contenido porque atrapa errores de frontmatter en tiempo de construccion. Las definiciones de esquema Zod son legibles incluso si TypeScript es nuevo para ti.

¿Que pasa con los comentarios de WordPress?

Astro es un generador de sitios estaticos, asi que no hay sistema de comentarios integrado. Puedes agregar Giscus (usa GitHub Discussions), Disqus o Hyvor Talk. Personalmente, elimine los comentarios por completo. La mayoria de los mios eran spam.

¿Perdere mis rankings SEO?

Con redirecciones 301 apropiadas, los rankings deberian transferirse. Vi una pequena caida durante unas dos semanas mientras Google reprocesaba cosas, luego se recupero. Las cargas de pagina mas rapidas de Astro realmente ayudaron mis rankings despues.

¿Puedo usar este proceso para un sitio WooCommerce?

Para las partes de contenido (posts de blog, paginas), si. Pero si tienes una tienda WooCommerce con productos, carrito y checkout, Astro solo no reemplazara eso. Necesitarias una capa de comercio headless como Snipcart o la Storefront API de Shopify junto con Astro.

¿Que si mis posts usan shortcodes de WordPress?

Los shortcodes no se convierten. El exportador de markdown los vuelca como texto plano. Necesitaras reemplazarlos con componentes MDX o simplemente eliminarlos. Use Codex CLI para encontrar todos los shortcodes a traves de mis archivos y convertir los comunes en equivalentes MDX.

Concluyendo

Mover de WordPress a Astro tomo un dia de trabajo enfocado, y me alegro de haberlo hecho. Mi sitio carga mas rapido, los costos de hosting pasaron de $X/mes a cero, y escribir en archivos MDX supera al editor de WordPress para mi flujo de trabajo.

Las herramientas que lo hicieron practico: wordpress-export-to-markdown para la conversion inicial, y Codex CLI para todo el reformateo archivo por archivo que no iba a hacer a mano. Las colecciones de contenido de Astro loataron todo junto con validacion con seguridad de tipos que atrapo errores en tiempo de construccion.

Si has estado posponiendo esto como yo lo hacia, solo empieza con un punado de posts y ve como va. El proceso es mas mecanico que creativo, y las herramientas manejan la mayor parte.