Auditar y migrar un sitio existente al estándar, página a página

La home pesaba ciento veinticuatro kilobytes y mil seiscientas líneas de HTML. Dentro, el schema estaba horneado a mano —dos bloques enormes de JSON-LD— y entre ellos, un AggregateRating de cinco estrellas con reseñas de clientes que no existían. El blog era un solo index.html de doscientos sesenta y cuatro kilobytes listando ciento ochenta y cinco posts sin paginación. Y aun así, ese sitio estaba vivo, rankeaba y traía clientes. Ese es el caso que casi todo el sistema no cubre: no la hoja en blanco, sino el sitio que ya existe y se quedó atrás del estándar. No puedes apagarlo y rehacerlo —es la fuente de ingresos— y tampoco puedes dejarlo como está. Migrarlo es un problema distinto al de construirlo, y necesita su propio método.

La tentación es el big-bang: reescribir todo de una vez y desplegar en una sola noche. Es la forma más rápida de tumbar un sitio que daba dinero, porque si algo sale mal —y con cincuenta cambios simultáneos, algo sale mal— no sabes cuál fue. El método que funciona es lo contrario: inventario, auditoría contra una vara fija, y un bucle que toca una página, aprende de ella, y devuelve ese aprendizaje al sistema antes de pasar a la siguiente. Lo que sigue es ese método, el que usamos para llevar un sitio insignia ya publicado al estándar de esta plantilla, una página a la vez.

Por qué página por página y no de un golpe

Un sitio vivo tiene activos que no se ven en el código: tráfico, enlaces entrantes, posiciones ganadas, confianza acumulada. Un big-bang los pone todos en riesgo a la vez. La migración incremental convierte un salto al vacío en una escalera: cada página es un peldaño que verificas antes de subir al siguiente, y mientras tanto el sitio viejo sigue intacto, sirviendo a sus visitantes, hasta que el nuevo esté verde de punta a punta. Si una página falla, revisas un cambio, no cincuenta. Es la misma lógica que las migraciones de URLs que Google recomienda hacer por lotes y monitoreando: el cambio grande se descompone en cambios pequeños, observables y reversibles.

Paso 1 — Inventario: cada página y su nivel

Antes de tocar nada, lista todas las páginas y asigna a cada una su nivel —L1 inicio, L2 índice, L3 ficha, L4 variante— y una prioridad. La prioridad no es estética: es por riesgo y valor. P0 es bloqueante o peligroso —algo que viola una regla dura o que sangra SEO—; P1 es alto valor; P2, medio; P3, pulido. Una home con reseñas fabricadas es P0 aunque «se vea bien»; una página legal correcta pero fea es P3. Ese inventario es el mapa: te dice cuántas páginas hay, de qué nivel, y por dónde empezar sin que el orden lo decida el capricho.

Paso 2 — La vara: auditar contra el estándar

Cada página se mide contra el mismo checklist canónico, sin excepciones. Esa vara fija es lo que hace comparable una auditoría de once páginas y lo que convierte un difuso «el sitio está viejo» en una tabla concreta de qué le falta a cada una:

• title de 60 caracteres o menos, con la palabra clave al frente.
• description de 150 a 160 caracteres, con llamada a la acción.
• canonical correcto.
• og:image presente y válido.
• JSON-LD apropiado al tipo de página y sin datos fabricados.
• H1 único y legible, sin palabras pegadas.
• Usa módulos canónicos, no HTML horneado.
• Contenido en colección si es un L2 o L3.
• astro check en cero y build verde.

Paso 3 — Los hallazgos que se repiten

Auditar sitios reales revela los mismos defectos una y otra vez, y conocerlos te deja atacarlos de raíz —en el sistema— en lugar de página por página.

El más grave es el contenido fabricado: un AggregateRating y reseñas con autores inventados, horneados en el JSON-LD de la home. Es P0 absoluto: viola la regla de cero contenido fabricado y arriesga una acción manual de Google por spam de rich snippets. Se quita, no se negocia —lo desarrollamos en Por qué nunca auto-emitir reseñas—.

El segundo es el og:image ausente: una página, clásicamente la de contacto, que al compartirse en redes sale sin imagen. La cura no es parchar esa página: es que lib/seo.ts provea un og:image global por defecto, de modo que ninguna página pueda publicarse sin uno. Un valor por defecto a prueba de fallos elimina la clase entera de defecto, no una instancia.

El tercero es el H1 con palabras pegadas: un encabezado donde un <br> o un <span> sin espacio produce «desarrollo web que genera» convertido en «desarrollo web quegenera». Es invisible en el editor y visible para el lector y el buscador; se caza revisando el texto renderizado, no el código fuente.

El cuarto es la deuda silenciosa: <style> inline repetido en cada página y schema horneado a mano. Se paga moviendo el estilo a tokens y el schema a lib/seo.ts, donde se mantiene una vez y se hereda en todas.

Paso 4 — El bucle de mejora bidireccional

Aquí está el corazón del método, y lo que lo vuelve acumulativo en lugar de repetitivo. Cada página se trabaja en un bucle que va y vuelve entre el sitio y la guía:

1. Auditas la página contra la vara y anotas qué tiene y qué le falta.
2. Migras la página al estándar —módulos, colección, schema centralizado—.
3. Extraes el aprendizaje: lo que esa página te enseñó y la guía aún no decía —un patrón nuevo, un error nuevo, una decisión— y lo devuelves a la guía como contenido. Este artículo, y los cuatro que enlaza al final, nacieron exactamente así.
4. Verificas: astro check en cero, build verde, y el gate real de deploy.
5. Cuando la guía ya tiene todo, esa guía enriquecida se aplica de vuelta a las páginas que faltan, ahora con las respuestas resueltas de antemano.

El bucle es bidireccional a propósito: cada página mejora la guía, y la guía mejorada mejora las páginas siguientes. La primera página de un tipo es lenta porque enseña; la segunda del mismo tipo es rápida porque ya hay un artículo que la guía. Al terminar no tienes solo un sitio migrado: tienes un sistema que aprendió, listo para el siguiente sitio. Esa es la diferencia entre arreglar once páginas y construir un método que arregla la doceava más rápido.

Paso 5 — Las decisiones de página que se repiten

Tres disyuntivas aparecen casi siempre, y conviene resolverlas con criterio, no por inercia:

• Cotizar contra contacto. El estándar usa un solo /contacto. Muchos sitios arrastran un /cotizar separado —a veces hasta un cotizar.html duplicado en la raíz—. La regla: fusiónalos en un formulario con una variante de «cotización», salvo que la cotización tenga un flujo propio que lo justifique. Un duplicado a medias confunde a Google y al usuario.
• La página de gracias. La confirmación tras enviar un formulario debe llevar noindex —no aporta nada en buscadores—, un WebPage mínimo, una llamada a la acción de regreso y el disparo del seguimiento de conversión. Es la única página del sitio que de verdad quieres fuera del índice.
• Directorio contra perfiles de blog. Si el sitio acumuló perfiles de negocios locales como posts sueltos, no los dejes dispersos: modélalos como colección y decide su relación con el directorio, para no tener la misma entidad en dos lugares peleando por el mismo término.

Patrones avanzados

El gate real no es el build local. Cada peldaño se cierra con astro check en cero y un build local verde —pero el local puede mentir en ambos sentidos—. Un desajuste del lockfile, una caché corrupta, una diferencia de entorno: cualquiera produce un falso negativo (o, peor, un falso positivo). El gate real es la Action de integración continua en verde, que compila en un entorno limpio. Hasta que la Action no pase, la página no está migrada: está escrita.

No tocar producción hasta el final. El sitio viejo es tu red de seguridad. La reconstrucción vive en un repositorio o rama aparte, se despliega a una URL de staging, se verifica entera, y solo entonces se corta el dominio —una vez, con todo confirmado—. Apagar el viejo antes de tener el nuevo verde es cambiar de avión en pleno vuelo.

La fricción del entorno es parte del trabajo. Migrar sitios reales topa con detalles del entorno que no salen en los tutoriales: sistemas de archivos que no permiten sobreescribir como esperas, cachés que no se purgan al primer intento, CDNs que sirven la versión vieja diez minutos después del deploy correcto. Documenta cada uno la primera vez que lo encuentres; el segundo sitio se beneficia del primero.

Edge cases

El source perdido. A veces el repositorio solo tiene el build desplegado —HTML plano, sin src/, sin package.json—. Entonces la migración empieza por una decisión: reconstruir sobre la plantilla (recomendado), recuperar el source, o parchear el HTML vivo como hotfix mientras tanto. Un P0 como reseñas fabricadas puede justificar el hotfix directo al build mientras se reconstruye en paralelo.

El sitio que cambia de stack y de deploy a la vez. Si además de migrar el código cambias el método de despliegue (de Pages estático a build en CI, por ejemplo), separa los dos cambios: primero el deploy nuevo verificado, luego la migración del contenido. Cambiar las dos cosas en el mismo salto multiplica las variables cuando algo falla.

El contenido de terceros que parece fabricado pero no lo es. Cuidado con la limpieza con tijera gruesa: un directorio puede tener calificaciones de negocios reales que sí son verificables. Antes de borrar todo AggregateRating, confirma cuáles son auto-reseñas de la marca (fuera) y cuáles son datos reales de terceros (se quedan).

Tabla: hallazgo → acción

Hallazgo frecuente	Prioridad	Acción de raíz
Reseñas / AggregateRating fabricados	P0	Quitar; no auto-emitir (regla B4)
og:image ausente	P0/P1	Valor por defecto global en lib/seo.ts
H1 con palabras pegadas	P1	Corregir marcado; revisar el render
Blog monolítico sin paginación	P1	Migrar a colección + taxonomías
<style> inline / schema horneado	P2	Tokens + lib/seo.ts
/cotizar duplicado	P2	Fusionar con /contacto
Página de gracias indexable	P3	noindex + WebPage + tracking

Checklist

• Inventaría todas las páginas con su nivel L1–L4 y su prioridad por riesgo (P0–P3).
• Audita cada una contra la vara canónica; convierte «está viejo» en una lista concreta.
• Ataca primero los P0 (contenido fabricado, og:image) de raíz, en el sistema.
• Trabaja en bucle: audita, migra, devuelve el aprendizaje a la guía, verifica.
• Resuelve cotizar/contacto, la página de gracias (noindex) y directorio/perfiles con criterio.
• No toques producción hasta que el nuevo esté verde; el sitio viejo es la red de seguridad.
• Cierra con astro check en cero, build verde y, el gate real, la Action en verde.

Preguntas frecuentes

¿Por qué no reescribir todo el sitio de una vez?

Porque un sitio vivo tiene tráfico y posiciones que no quieres arriesgar en un solo salto. La migración incremental aísla el riesgo: si algo falla, fue el último peldaño, no cincuenta cambios simultáneos. Y el sitio viejo sigue sirviendo mientras tanto.

¿Qué hace que un hallazgo sea P0?

Que bloquee o que arriesgue: contenido fabricado que puede penalizar el dominio, o un defecto que sangra SEO o conversión. Un P0 se atiende antes que cualquier mejora estética, aunque la página se vea bien. La prioridad es por riesgo, no por gusto.

¿Qué es exactamente el bucle de mejora bidireccional?

Trabajar cada página de modo que su aprendizaje vuelva a la guía, y que la guía enriquecida mejore las páginas siguientes. El sitio mejora la guía; la guía mejora el sitio. Al final tienes un método reutilizable, no solo páginas arregladas, y el siguiente sitio se migra más rápido.

¿Por qué el build local no es el gate?

Porque un desajuste de dependencias o de entorno en tu máquina puede mentir en ambos sentidos —dar verde con algo roto o rojo con algo sano—. La verdad la dice la Action de CI en verde, que compila en un entorno limpio y reproducible. El build local es necesario pero no suficiente.

¿Cuándo apago el sitio viejo?

Nunca antes de que el nuevo esté verde y verificado de punta a punta, incluida la Action. El sitio viejo es tu red de seguridad hasta el último momento; el corte de dominio se hace una sola vez, con todo confirmado, no a mitad de la migración.

¿Y si el repositorio solo tiene el build, sin código fuente?

Entonces decides primero: reconstruir sobre la plantilla, recuperar el source o parchear el HTML vivo como hotfix. Un P0 grave (reseñas fabricadas) puede justificar el hotfix directo al build mientras reconstruyes en paralelo, para no dejar el riesgo activo.

Sigue leyendo

• Sitio servicios-céntrico: retirar el andamiaje de catálogo — la conversión de arquetipo dentro de esta migración.
• Migrar un blog legacy a Content Collections — el paso del blog, en detalle.
• Portafolio honesto: proyectos vs casos y Páginas legales en México — dos páginas del inventario, a fondo.
• Por qué nunca auto-emitir reseñas: la regla B4 — el P0 más común al auditar.
• Fuente externa: Google Search Central — Site moves with URL changes.