El cambio de Astro 7 al motor de markdown Sätteri, basado en Rust, está convirtiendo los bloques de matemáticas (display-math) en código plano, eliminando los anclajes de los encabezados y descartando las opciones de markdown personalizadas; un problema crítico para cualquiera que haya actualizado y ahora vea ecuaciones rotas en su sitio.

Si dependes de matemáticas estilo LaTeX, enlaces automáticos en encabezados o plugins de markdown personalizados, la actualización puede hacer que tu contenido sea ilegible y tu navegación inutilizable, por lo que solucionarlo rápidamente es esencial.

Por qué la actualización rompió las cosas

Astro ahora ejecuta Sätteri como su procesador de Markdown principal. Sätteri cambia el orden en que se aplican los plugins: ejecuta el resaltado de sintaxis (syntax highlighting) antes de los plugins HTML-AST (HAST) que hayas configurado. Ese cambio significa que tres patrones comunes dejan de funcionar:

  • Display math – los bloques delimitados por $$ … $$ se tratan como código ordinario porque el resaltador se ejecuta primero.
  • Heading anchors – los plugins que generan slugs (IDs amigables para URLs) y luego crean enlaces automáticos en esos encabezados ya no detectan los IDs, por lo que los enlaces nunca se crean.
  • Custom options – cualquier configuración adicional que hayas pasado directamente al procesador Sätteri es ignorada; Astro solo reenvía tres campos predefinidos.

Las soluciones concretas

1. Renderiza las matemáticas en el markdown-AST (MDAST) en lugar del HTML-AST

El pipeline de markdown de Astro tiene dos espacios para plugins:

  • mdastPlugins – se ejecutan en el árbol de markdown analizado antes de convertirse en HTML.
  • hastPlugins – se ejecutan en el árbol HTML después de la conversión.

Debido a que el resaltador se ejecuta antes de hastPlugins, las matemáticas se convierten en un bloque de código. Mueve tu plugin de matemáticas a mdastPlugins.

export default {
  markdown: {
    mdastPlugins: [
      // put remark-math (or your custom math handler) here
    ],
    // leave hastPlugins for things that truly need HTML nodes
  }
}

Las configuraciones estándar instalan un generador de slugs seguido de un plugin de autolink. En Astro, el plugin integrado de heading-ID se ejecuta después de tu lista, dejando nada a lo que el plugin de autolink pueda adjuntarse. Coloca el plugin de slug primero en la lista, y luego el plugin de autolink.

export default {
  markdown: {
    mdastPlugins: [
      satteriSlug(),            // must be first
      satteriAutolinkHeadings() // runs after slug, sees IDs
    ]
  }
}

Ahora cada encabezado recibe un ID y el plugin de autolink puede envolverlo con el anclaje apropiado.

3. Coloca la configuración extra en el nivel superior del objeto markdown de Astro

Astro solo reenvía tres campos específicos al procesador Sätteri. Cualquier cosa que anides dentro del procesador (por ejemplo, un objeto shikiConfig) se descarta. Mueve esos ajustes adicionales al nivel superior de la configuración markdown.

export default {
  markdown: {
    shikiConfig: { theme: 'nord' }, // top-level, will be respected
    // other Astro-accepted fields …
    mdastPlugins: [/* … */],
    hastPlugins: [/* … */]
  }
}

Guía rápida de reemplazo para plugins comunes de remark

Plugin de remark antiguo Nueva flag de características de Astro
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

Cambia el nombre del plugin por la flag features.* correspondiente en tu configuración de Astro.

Mejores prácticas al portar plugins a Sätteri

  • Factory pattern – crea una nueva instancia de plugin por documento para evitar la fuga de estado entre páginas.
  • Immutable nodes – nunca mutes un nodo in situ; devuelve un objeto de nodo nuevo para que el procesador pueda rastrear los cambios correctamente.
  • Insert helpers – usa ctx.insertBefore o ctx.insertAfter cuando necesites añadir nodos hermanos, en lugar de recortar el árbol manualmente.

Seguir estas reglas mantiene el procesador estable y evita errores difíciles de rastrear.

Qué vigilar a continuación

La documentación de Astro todavía enumera el antiguo orden de plugins como el predeterminado, por lo que los proyectos nuevos pueden heredar el comportamiento erróneo de forma involuntaria. Mantente atento a los próximos lanzamientos de Astro para un posible arreglo integrado que reordene el plugin interno de heading-ID. Mientras tanto, los pasos anteriores son la única forma confiable de restaurar el renderizado de matemáticas, los anclajes de encabezados y las opciones de markdown personalizadas tras la migración a Astro 7.

Conclusión: Cambiar al motor Sätteri de Astro 7 requiere mover el manejo de matemáticas a mdastPlugins, anteponer el plugin de slug antes de los autolinks y extraer cualquier configuración de markdown adicional del objeto del procesador; una vez realizados estos tres ajustes, las ecuaciones, los enlaces de navegación y las funciones de markdown personalizadas de tu sitio funcionarán como antes.