Astro 7’s switch to the Rust-based Sätteri markdown engine turned a smooth upgrade into a three-fold nightmare for sites that rely on math, heading anchors, and custom configuration. Inline equations still work, but display-math blocks appear as plain-text code snippets, heading IDs disappear, and any extra options you sprinkle into the Astro config are silently ignored. Developers who migrate from earlier Astro releases now have to rewrite plugins or risk broken pages.

Por qué este cambio es importante

El nuevo motor ejecuta un resaltador de sintaxis integrado antes que cualquier plugin proporcionado por el usuario y solo acepta tres campos de configuración de nivel superior. Estas opciones chocan con la forma en que la mayoría de los proyectos de Astro añaden funcionalidades: a través de plugins de remark (MDAST) y rehype (HAST) que esperan ejecutarse después del resaltado, y mediante un objeto de configuración permisivo que se transmite al analizador de markdown subyacente.

Las consecuencias se manifiestan en cualquier página que mezcle matemáticas estilo LaTeX con contenido regular. Las matemáticas en línea ($a+b$) se renderizan bien, pero un bloque de matemáticas en bloque ($$a+b$$) se envuelve en una etiqueta <pre>, mostrando el marcado en bruto en lugar de una ecuación formateada. Los anclajes de encabezado que habilitan los enlaces de la tabla de contenidos o los enlaces profundos (deep-linking) desaparecen porque el plugin de generación de IDs se ejecuta antes del manejador de IDs integrado, dejando nada a lo que el plugin de autolink pueda engancharse. Los desarrolladores que intentaron ajustar el resaltador de sintaxis Shiki con un objeto shikiConfig descubren que la configuración ha desaparecido sin dejar rastro.

Las soluciones técnicas

1. Renderizar las matemáticas antes del resaltado

La causa raíz es el orden de las operaciones: el resaltador de Sätteri reclama el texto primero, clasificando el bloque de matemáticas como código plano. Para recuperar las matemáticas, traslada el procesamiento a la capa MDAST (el árbol de sintaxis abstracta que representa el markdown antes de convertirse en HTML). Reemplaza cualquier plugin de matemáticas a nivel HAST por sus equivalentes en MDAST y ejecútalos antes del paso de resaltado. En la práctica, sustituye los plugins remark-math por una versión que se conecte a la etapa de análisis de markdown, y luego deja que el resaltador trabaje sobre los nodos matemáticos ya convertidos.

2. Reordenar los plugins de ID de encabezado

Los IDs de los encabezados son generados por un plugin integrado que ahora se ejecuta después de los plugins del usuario. Mueve los generadores de IDs o slugs personalizados al principio de la lista de plugins para que se ejecuten primero. Una secuencia típica que restaura los enlaces de anclaje es la siguiente:

  1. plugin de slug/ID
  2. plugin de autolink
  3. cualquier otro plugin de remark

Con los IDs establecidos desde el principio, el plugin de autolink puede adjuntar los elementos <a> esperados, y la tabla de contenidos apuntará a las secciones correctas.

3. Respetar el esquema de configuración estricto de Sätteri

Sätteri solo reconoce tres campos en la configuración de markdown de Astro. Cualquier otra cosa, como shikiConfig, se descarta silenciosamente. Para mantener activos los temas personalizados o los ajustes del resaltador, reubica esos ajustes en el nivel adecuado de la jerarquía de configuración de Astro.

Guía rápida de reemplazo

Si estás migrando un stack de markdown clásico de Astro, reemplaza los antiguos plugins de remark por las nuevas banderas de funcionalidad (feature flags) que Sätteri entiende:

  • remark-gfm → features.gfm
  • remark-frontmatter → features.frontmatter
  • remark-math → features.math
  • remark-directive → features.directive
  • remark-smartypants → features.smartPunctuation
  • remark-wiki-link → features.wikilinks

Estas banderas habilitan las mismas capacidades sin necesidad de cargar un plugin por separado.

Reglas para que los plugins funcionen correctamente con Sätteri

  • Solo una pasada – Los plugins ven el árbol una sola vez; no pueden volver a visitar nodos creados más adelante en el proceso.
  • Fábrica para el estado – Crea un objeto de estado nuevo para cada página para evitar la fuga de datos entre páginas.
  • Nodos inmutables – Devuelve un nuevo nodo cuando necesites realizar un cambio; mutar un nodo existente puede romper los pasos de procesamiento posteriores.
  • Sin fragmentos raíz – Inserta elementos hermanos a través de los ayudantes de inserción proporcionados en lugar de crear un nodo de fragmento de nivel superior.

Cuando adaptes un plugin existente, no confíes en el ejemplo de salida del README. Renderiza el HTML del plugin original, captura ese marcado y úsalo como punto de referencia para tu versión compatible con Sätteri.

Conclusión

El motor Sätteri de Astro 7 aporta velocidad, pero obliga a reordenar la cadena de procesamiento de markdown: renderizar las matemáticas en el nivel MDAST, colocar los plugins de ID de encabezados al principio y limitar la configuración a los tres campos aceptados. Siga el mapeo de feature-flags, respete las reglas de paso único y de nodos inmutables, y restaurará las matemáticas, los anclajes y los temas personalizados de los que depende su sitio. El esfuerzo es inicial; la recompensa es un pipeline de markdown más rápido y predecible.