Astro 7 Upgrade Breaks Math, Heading Links and Custom Options – How to Fix It

Der Wechsel von Astro 7 zur Rust-basierten Sätteri-Markdown-Engine verwandelt Display-Math-Blöcke in einfachen Code, entfernt Überschriften-Anker und verwirft benutzerdefinierte Markdown-Optionen – ein großes Problem für alle, die ein Upgrade durchgeführt haben und nun fehlerhafte Gleichungen auf ihrer Website sehen.

Wenn Sie auf LaTeX-Style-Mathematik, automatische Überschriften-Links oder maßgeschneiderte Markdown-Plugins angewiesen sind, kann das Upgrade Ihren Inhalt unlesbar und Ihre Navigation unbrauchbar machen, weshalb eine schnelle Behebung unerlässlich ist.

Warum das Upgrade Probleme verursacht hat

Astro nutzt nun Sätteri als seinen zentralen Markdown-Prozessor. Sätteri ändert die Reihenfolge, in der Plugins angewendet werden: Es führt das Syntax-Highlighting aus, bevor die HAST-Plugins (HTML-AST) ausgeführt werden, die Sie eventuell konfiguriert haben. Diese Verschiebung führt dazu, dass drei gängige Muster nicht mehr funktionieren:

• Display-Math – Blöcke, die mit $$ … $$ abgegrenzt sind, werden als gewöhnlicher Code behandelt, da das Highlighting zuerst ausgeführt wird.
• Überschriften-Anker – Plugins, die Slugs (URL-freundliche IDs) generieren und diese Überschriften dann automatisch verlinken, sehen die IDs nicht mehr, sodass die Links nie erstellt werden.
• Benutzerdefinierte Optionen – alle zusätzlichen Einstellungen, die Sie direkt an den Sätteri-Prozessor übergeben haben, werden ignoriert; Astro leitet nur drei vordefinierte Felder weiter.

Die konkreten Lösungen

1. Mathematik auf dem markdown-AST (MDAST) statt auf dem HTML-AST rendern

Die Markdown-Pipeline von Astro hat zwei Plugin-Slots:

• mdastPlugins – werden auf dem geparsten Markdown-Baum ausgeführt, bevor dieser zu HTML wird.
• hastPlugins – werden auf dem HTML-Baum nach der Konvertierung ausgeführt.

Da das Highlighting vor hastPlugins ausgeführt wird, wird die Mathematik in einen Code-Block umgewandelt. Verschieben Sie Ihr Mathematik-Plugin zu mdastPlugins.

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

2. Reihenfolge von Slug- und Autolink-Plugins für Überschriften ändern

Standard-Setups installieren einen Slug-Generator, gefolgt von einem Autolink-Plugin. In Astro wird das integrierte Heading-ID-Plugin nach Ihrer Liste ausgeführt, sodass für das Autolink-Plugin nichts mehr zum Verknüpfen vorhanden ist. Platzieren Sie das Slug-Plugin an erster Stelle in der Liste, gefolgt vom Autolink-Plugin.

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

Nun erhält jede Überschrift eine ID und das Autolink-Plugin kann sie mit dem entsprechenden Anker umschließen.

3. Zusätzliche Konfiguration auf die oberste Ebene des Astro-Markdown-Objekts setzen

Astro leitet nur drei spezifische Felder an den Sätteri-Prozessor weiter. Alles, was Sie innerhalb des Prozessors verschachteln (zum Beispiel ein shikiConfig-Objekt), wird verworfen. Verschieben Sie diese zusätzlichen Einstellungen auf die oberste Ebene der markdown-Konfiguration.

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

Schneller Leitfaden zum Ersetzen gängiger remark-Plugins

Altes remark-Plugin	Neues Astro Feature-Flag
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

Ersetzen Sie den Plugin-Namen durch das entsprechende features.*-Flag in Ihrer Astro-Konfiguration.

Best Practices beim Portieren von Plugins zu Sätteri

• Factory-Pattern – Erstellen Sie pro Dokument eine neue Plugin-Instanz, um zu verhindern, dass Zustände zwischen den Seiten durchsickern (State Leaking).
• Immutable Nodes – Mutieren Sie niemals einen Knoten direkt; geben Sie ein neues Knoten-Objekt zurück, damit der Prozessor Änderungen korrekt verfolgen kann.
• Insert-Helper – Verwenden Sie ctx.insertBefore oder ctx.insertAfter, wenn Sie Geschwisterknoten (Sibling Nodes) hinzufügen müssen, anstatt den Baum manuell zu manipulieren (Splicing).

Das Befolgen dieser Regeln hält den Prozessor stabil und verhindert schwer nachverfolgbare Bugs.

Worauf man als Nächstes achten sollte

Die Dokumentation von Astro führt immer noch die alte Plugin-Reihenfolge als Standard auf, sodass neue Projekte das fehlerhafte Verhalten unbeabsichtigt übernehmen könnten. Achten Sie auf kommende Astro-Releases auf einen möglichen integrierten Fix, der das interne Heading-ID-Plugin neu ordnet. In der Zwischenzeit sind die oben genannten Schritte der einzige zuverlässige Weg, um die Mathematik-Darstellung, Überschriften-Anker und benutzerdefinierte Markdown-Optionen nach dem Wechsel zu Astro 7 wiederherzustellen.

Fazit: Der Wechsel zur Sätteri-Engine von Astro 7 erfordert das Verschieben der Mathematik-Verarbeitung zu mdastPlugins, das Voranstellen des Slug-Plugins vor die Autolinks und das Herauslösen aller zusätzlichen Markdown-Einstellungen aus dem Prozessor-Objekt; sobald diese drei Anpassungen vorgenommen wurden, funktionieren die Gleichungen, Navigationslinks und benutzerdefinierten Markdown-Funktionen Ihrer Website wie zuvor.