Il passaggio di Astro 7 al motore markdown Sätteri, basato su Rust, sta trasformando i blocchi di display-math in semplice codice, rimuovendo gli anchor degli heading e scartando le opzioni markdown personalizzate – un problema critico per chiunque abbia effettuato l'aggiornamento e veda ora equazioni corrotte sul proprio sito.

Se fai affidamento sulla matematica in stile LaTeX, sui link automatici agli heading o su plugin markdown personalizzati, l'aggiornamento può rendere il tuo contenuto illeggibile e la navigazione inutilizzabile, quindi è essenziale risolvere il problema rapidamente.

Perché l'aggiornamento ha causato problemi

Astro ora utilizza Sätteri come processore Markdown principale. Sätteri cambia l'ordine in cui i plugin vengono applicati: esegue l'evidenziazione della sintassi (syntax highlighting) prima dei plugin HTML-AST (HAST) che potresti aver configurato. Questo cambiamento significa che tre schemi comuni smettono di funzionare:

  • Display math – i blocchi delimitati da $$ … $$ vengono trattati come codice ordinario perché l'evidenziatore viene eseguito per primo.
  • Heading anchors – i plugin che generano slug (ID compatibili con gli URL) e poi creano link automatici a quegli heading non vedono più gli ID, quindi i link non vengono mai creati.
  • Custom options – qualsiasi impostazione extra passata direttamente al processore Sätteri viene ignorata; Astro inoltra solo tre campi predefiniti.

Le soluzioni concrete

1. Renderizzare la matematica sull'MDAST (markdown-AST) invece che sull'HAST (HTML-AST)

La pipeline markdown di Astro ha due slot per i plugin:

  • mdastPlugins – vengono eseguiti sull'albero markdown analizzato prima che diventi HTML.
  • hastPlugins – vengono eseguiti sull'albero HTML dopo la conversione.

Poiché l'evidenziatore viene eseguito prima di hastPlugins, la matematica viene trasformata in un blocco di codice. Sposta il tuo plugin per la matematica in mdastPlugins.

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

Le configurazioni standard installano un generatore di slug seguito da un plugin di autolink. In Astro, il plugin integrato per l'ID degli heading viene eseguito dopo la tua lista, lasciando nulla a cui il plugin di autolink possa agganciarsi. Posiziona il plugin dello slug per primo nella lista, poi il plugin di autolink.

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

Ora ogni heading riceve un ID e il plugin di autolink può avvolgerlo con l'anchor appropriato.

3. Inserire la configurazione extra al livello superiore dell'oggetto markdown di Astro

Astro inoltra solo tre campi specifici al processore Sätteri. Qualsiasi cosa tu annidi all'interno del processore (ad esempio un oggetto shikiConfig) viene scartata. Sposta queste impostazioni extra al livello superiore della configurazione markdown.

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

Guida rapida alla sostituzione per i plugin remark comuni

Vecchio plugin remark Nuovo flag feature di 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

Sostituisci il nome del plugin con il corrispondente flag features.* nella tua configurazione Astro.

Best practice per il porting dei plugin in Sätteri

  • Factory pattern – crea una nuova istanza del plugin per ogni documento per evitare la dispersione dello stato tra le pagine.
  • Immutable nodes – non mutare mai un nodo sul posto; restituisci un nuovo oggetto nodo in modo che il processore possa tracciare correttamente le modifiche.
  • Insert helpers – usa ctx.insertBefore o ctx.insertAfter quando hai bisogno di aggiungere nodi fratelli, invece di manipolare l'albero manualmente.

Seguire queste regole mantiene il processore stabile e previene bug difficili da tracciare.

Cosa monitorare in futuro

La documentazione di Astro elenca ancora il vecchio ordine dei plugin come predefinito, quindi i nuovi progetti potrebbero ereditare involontariamente il comportamento errato. Tieni d'occhio i prossimi rilasci di Astro per un possibile fix integrato che riordini il plugin interno per l'ID degli heading. Nel frattempo, i passaggi sopra indicati sono l'unico modo affidabile per ripristinare il rendering della matematica, gli anchor degli heading e le opzioni markdown personalizzate dopo il passaggio ad Astro 7.

In sintesi: Il passaggio al motore Sätteri di Astro 7 richiede di spostare la gestione della matematica in mdastPlugins, anticipare il plugin dello slug prima degli autolink e spostare ogni impostazione markdown extra fuori dall'oggetto del processore; una volta effettuati questi tre aggiustamenti, le equazioni del tuo sito, i link di navigazione e le funzionalità markdown personalizzate torneranno a funzionare come prima.