Astro 7’s overstap naar de op Rust gebaseerde Sätteri-markdownengine heeft een soepele upgrade veranderd in een drievoudige nachtmerrie voor sites die afhankelijk zijn van wiskunde, koptekst-ankers en aangepaste configuratie. Inline vergelijkingen werken nog wel, maar display-math-blokken verschijnen als gewone tekstcodefragmenten, koptekst-ID's verdwijnen en alle extra opties die je in de Astro-configuratie toevoegt, worden stilzwijgend genegeerd. Ontwikkelaars die migreren vanuit eerdere Astro-versies moeten nu plugins herschrijven of het risico lopen op kapotte pagina's.

Waarom de verandering belangrijk is

De nieuwe engine voert een ingebouwde syntax highlighter uit voordat gebruikers-plugins worden geladen en accepteert slechts drie configuratievelden op het hoogste niveau. Deze keuzes botsen met de manier waarop de meeste Astro-projecten functies toevoegen: via remark (MDAST) en rehype (HAST) plugins die verwachten te draaien ná de syntax highlighting, en via een permissief config-object dat wordt doorgegeven aan de onderliggende markdown-parser.

De gevolgen zijn merkbaar op elke pagina die LaTeX-stijl wiskunde combineert met reguliere inhoud. Inline wiskunde ($a+b$) wordt correct weergegeven, maar een display-blok ($$a+b$$) wordt in een <pre>-tag geplaatst, waardoor de ruwe markup in plaats van een geformatteerde vergelijking wordt getoond. Koptekst-ankers die de links in de inhoudsopgave of deep-linking aandrijven, verdwijnen omdat de ID-generatie-plugin draait vóór de ingebouwde ID-handler, waardoor er niets overblijft waar de autolink-plugin zich op kan aansluiten. Ontwikkelaars die probeerden de Shiki syntax highlighter fijn te stellen met een shikiConfig-object, merken dat de instelling spoorloos is verdwenen.

De technische oplossingen

1. Render wiskunde vóór de syntax highlighting

De hoofdoorzaak is de volgorde van bewerkingen: de highlighter van Sätteri claimt eerst de tekst en classificeert het wiskundeblok als gewone code. Om de wiskunde terug te krijgen, moet de verwerking worden verplaatst naar de MDAST-laag (de abstract syntax tree die markdown representeert voordat het HTML wordt). Vervang alle wiskunde-plugins op HAST-niveau door hun MDAST-equivalenten en voer deze uit vóór de highlighter-stap. In de praktijk vervang je remark-math-plugins door een versie die zich koppelt aan de markdown-parsingfase, zodat de highlighter vervolgens kan werken op de reeds omgezette wiskundeknooppunten.

2. Herordening van koptekst-ID-plugins

Koptekst-ID's worden gegenereerd door een ingebouwde plugin die nu wordt uitgevoerd ná de plugins van de gebruiker. Verplaats aangepaste ID- of slug-generators naar de bovenkant van de pluginlijst, zodat ze als eerste draaien. Een typische volgorde die ankerlinks herstelt, ziet er als volgt uit:

  1. slug/ID plugin
  2. autolink plugin
  3. alle andere remark plugins

Doordat de ID's vroegtijdig aanwezig zijn, kan de autolink-plugin de verwachte <a>-elementen toevoegen en zal de inhoudsopgave naar de juiste secties verwijzen.

3. Houd rekening met het strikte configuratieschema van Sätteri

Sätteri erkent slechts drie velden in de Astro-markdownconfiguratie. Alles wat daar buiten valt, zoals shikiConfig, wordt stilzwijgend verwijderd. Om aangepaste thema's of highlighter-aanpassingen te behouden, moet je deze instellingen verplaatsen naar het juiste niveau in de Astro-configuratiehiërarchie.

Snelle vervangingsgids

Als je een klassieke Astro-markdownstack port, vervang dan de oude remark-plugins door de nieuwe feature flags die Sätteri begrijpt:

  • 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

Deze flags maken dezelfde mogelijkheden mogelijk zonder dat er een aparte plugin geladen hoeft te worden.

Regels om plugins compatibel te houden met Sätteri

  • Slechts één pass – Plugins zien de boom slechts één keer; ze kunnen geen nodes opnieuw bezoeken die later in de pipeline zijn aangemaakt.
  • Factory voor state – Maak voor elke pagina een nieuw state-object aan om datalekken tussen pagina's te voorkomen.
  • Immutable nodes – Retourneer een nieuwe node wanneer je een wijziging wilt doorvoeren; het muteren van een bestaande node kan de daaropvolgende verwerkingsstappen verstoren.
  • Geen root-fragmenten – Voeg broer-nodes toe via de meegeleverde hulpfuncties voor invoeging, in plaats van een fragment-node op het hoogste niveau te maken.

Wanneer je een bestaande plugin aanpast, vertrouw dan niet op de voorbeeldoutput in de README. Render de HTML van de originele plugin, vang die markup op en gebruik deze als referentiepunt voor je Sätteri-compatibele versie.

Conclusie

De Sätteri-engine van Astro 7 zorgt voor snelheid, maar dwingt een herordening van de markdown-verwerkingsketen af: render wiskunde op MDAST-niveau, plaats heading-ID-plugins vooraan en beperk de configuratie tot de drie geaccepteerde velden. Volg de feature-flag-mapping, respecteer de single-pass- en immutable-node-regels, en je herstelt de wiskunde, ankers en aangepaste theming waar je site van afhankelijk is. De inspanning is vooraf; de beloning is een voorspelbaardere, snellere markdown-pipeline.