Le passage d'Astro 7 au moteur markdown Sätteri, basé sur Rust, a transformé une mise à jour fluide en un triple cauchemar pour les sites qui s'appuient sur les mathématiques, les ancres de titres et la configuration personnalisée. Les équations en ligne fonctionnent toujours, mais les blocs de mathématiques en mode display apparaissent comme de simples extraits de code texte brut, les identifiants de titres disparaissent, et toute option supplémentaire ajoutée à la configuration d'Astro est ignorée en silence. Les développeurs qui migrent depuis des versions antérieures d'Astro doivent désormais réécrire des plugins ou risquer des pages cassées.

Pourquoi ce changement est important

Le nouveau moteur exécute un surligneur de syntaxe intégré avant tout plugin fourni par l'utilisateur et n'accepte que trois champs de configuration de premier niveau. Ces choix entrent en conflit avec la manière dont la plupart des projets Astro ajoutent des fonctionnalités : via des plugins remark (MDAST) et rehype (HAST) qui s'attendent à s'exécuter après la coloration syntaxique, et via un objet de configuration permissif qui est transmis au parseur markdown sous-jacent.

Les conséquences se manifestent sur n'importe quelle page mélangeant des mathématiques de style LaTeX avec du contenu régulier. Les mathématiques en ligne ($a+b$) s'affichent correctement, mais un bloc de type display ($$a+b$$) est enveloppé dans une balise <pre>, affichant le marquage brut au lieu d'une équation formatée. Les ancres de titres qui alimentent les liens de la table des matières ou les liens profonds disparaissent car le plugin de génération d'ID s'exécute avant le gestionnaire d'ID intégré, ne laissant rien sur quoi le plugin autolink puisse s'accrocher. Les développeurs qui ont tenté d'affiner le surligneur de syntaxe Shiki avec un objet shikiConfig constatent que le paramètre a disparu sans laisser de trace.

Les correctifs techniques

1. Rendre les mathématiques avant la coloration syntaxique

La cause profonde est l'ordre des opérations : le surligneur de Sätteri revendique le texte en premier, classant le bloc mathématique comme du code brut. Pour récupérer les mathématiques, déplacez le traitement vers la couche MDAST (l'arbre de syntaxe abstrait qui représente le markdown avant qu'il ne devienne du HTML). Remplacez tous les plugins mathématiques de niveau HAST par leurs équivalents MDAST et exécutez-les avant l'étape du surligneur. En pratique, remplacez les plugins remark-math par une version qui s'accroche à l'étape de parsing du markdown, puis laissez le surligneur travailler sur les nœuds mathématiques déjà convertis.

2. Réorganiser les plugins d'ID de titres

Les ID de titres sont générés par un plugin intégré qui s'exécute désormais après les plugins utilisateur. Déplacez les générateurs d'ID ou de slugs personnalisés en haut de la liste des plugins pour qu'ils s'exécutent en premier. Une séquence typique qui restaure les liens d'ancrage ressemble à ceci :

  1. plugin slug/ID
  2. plugin autolink
  3. tout autre plugin remark

Avec les ID en place dès le début, le plugin autolink peut attacher les éléments <a attendus, et la table des matières pointera vers les bonnes sections.

3. Respecter le schéma de configuration strict de Sätteri

Sätteri ne reconnaît que trois champs dans la configuration markdown d'Astro. Tout le reste, comme shikiConfig, est ignoré silencieusement. Pour conserver vos thèmes personnalisés ou vos ajustements de surligneur, déplacez ces paramètres au bon niveau dans la hiérarchie de configuration d'Astro.

Guide de remplacement rapide

Si vous portez une pile markdown Astro classique, remplacez les anciens plugins remark par les nouveaux indicateurs de fonctionnalités (feature flags) que Sätteri comprend :

  • 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

Ces indicateurs activent les mêmes capacités sans nécessiter le chargement d'un plugin séparé.

Règles pour que les plugins fonctionnent correctement avec Sätteri

  • Passage unique uniquement – Les plugins ne voient l'arbre qu'une seule fois ; ils ne peuvent pas revisiter des nœuds créés plus tard dans le pipeline.
  • Factory pour l'état – Créez un nouvel objet d'état pour chaque page afin d'éviter les fuites de données entre les pages.
  • Nœuds immuables – Retournez un nouveau nœud lorsque vous avez besoin d'un changement ; la mutation d'un nœud existant peut briser les étapes de traitement ultérieures.
  • Pas de fragments racines – Insérez des éléments frères via les helpers d'insertion fournis au lieu de créer un nœud de fragment de premier niveau.

Lorsque vous adaptez un plugin existant, ne vous fiez pas à la sortie d'exemple du README. Rendu le HTML du plugin original, capturez ce marquage et utilisez-le comme point de référence pour votre version compatible avec Sätteri.

À retenir

Le moteur Sätteri d'Astro 7 apporte de la rapidité, mais impose une réorganisation de la chaîne de traitement du markdown : rendez les mathématiques au niveau MDAST, placez les plugins d'ID de titres au début, et limitez la configuration aux trois champs acceptés. Suivez le mappage des feature-flags, respectez les règles de passage unique (single-pass) et de nœuds immuables (immutable-node), et vous restaurerez les mathématiques, les ancres et le thème personnalisé dont votre site dépend. L'effort se fait en amont ; la récompense est un pipeline markdown plus prévisible et plus rapide.