Astro 7’s switch to the Rust-based Sätteri markdown engine turned a smooth upgrade into a three-fold nightmare for sites that rely on math, heading anchors, and custom configuration. Inline equations still work, but display-math blocks appear as plain-text code snippets, heading IDs disappear, and any extra options you sprinkle into the Astro config are silently ignored. Developers who migrate from earlier Astro releases now have to rewrite plugins or risk broken pages.

Why the change matters

The new engine runs a built-in syntax highlighter before any user-supplied plugins and only accepts three top-level configuration fields. Those choices clash with the way most Astro projects add features: through remark (MDAST) and rehype (HAST) plugins that expect to run after highlighting, and through a permissive config object that passes through to the underlying markdown parser.

The fallout shows up on any page that mixes LaTeX-style math with regular content. Inline math ($a+b$) renders fine, but a display block ($$a+b$$) is wrapped in a <pre> tag, showing raw markup instead of a formatted equation. Heading anchors that power table-of-contents links or deep-linking vanish because the ID-generation plugin runs before the built-in ID handler, leaving nothing for the autolink plugin to latch onto. Developers who tried to fine-tune the Shiki syntax highlighter with a shikiConfig object find the setting disappeared without a trace.

The technical fixes

1. Render math before highlighting

The root cause is the order of operations: Sätteri’s highlighter claims the text first, classifying the math block as plain code. To reclaim the math, shift processing to the MDAST layer (the abstract syntax tree that represents markdown before it becomes HTML). Replace any HAST-level math plugins with their MDAST equivalents and run them before the highlighter step. In practice, swap out remark-math plugins for a version that hooks into the markdown parsing stage, then let the highlighter work on the already-converted math nodes.

2. Reorder heading-ID plugins

Heading IDs are generated by a built-in plugin that now executes after user plugins. Move custom ID or slug generators to the top of the plugin list so they run first. A typical sequence that restores anchor links looks like:

  1. slug/ID plugin
  2. autolink plugin
  3. any other remark plugins

With the IDs in place early, the autolink plugin can attach the expected <a> elements, and the table-of-contents will point to the right sections.

3. Respect Sätteri’s strict config schema

Sätteri only acknowledges three fields in the Astro markdown configuration. Anything else, such as shikiConfig, gets dropped silently. To keep custom themes or highlighter tweaks alive, relocate those settings to the proper level in the Astro config hierarchy.

Quick replacement guide

If you’re porting a classic Astro markdown stack, replace the old remark plugins with the new feature flags that Sätteri understands:

  • 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

These flags enable the same capabilities without requiring a separate plugin load.

Rules to keep plugins happy with Sätteri

  • Single pass only – Plugins see the tree once; they cannot revisit nodes created later in the pipeline.
  • Factory for state – Build a fresh state object for each page to avoid cross-page data leakage.
  • Immutable nodes – Return a new node when you need a change; mutating an existing node can break subsequent processing steps.
  • No root fragments – Insert siblings through the provided insertion helpers instead of creating a top-level fragment node.

When you adapt an existing plugin, don’t rely on the README’s example output. Render the original plugin’s HTML, capture that markup, and use it as the reference point for your Sätteri-compatible version.

Takeaway

เอนจิน Sätteri ของ Astro 7 ช่วยเพิ่มความเร็ว แต่ก็ทำให้ต้องมีการจัดลำดับขั้นตอนการประมวลผล markdown ใหม่: โดยต้องเรนเดอร์ math ในระดับ MDAST, วาง heading-ID plugins ไว้ที่ส่วนหน้าสุด และจำกัดการตั้งค่าไว้เพียงสามฟิลด์ที่กำหนดเท่านั้น หากปฏิบัติตามการทำ feature-flag mapping และปฏิบัติตามกฎ single-pass และ immutable-node คุณจะสามารถกู้คืนระบบ math, anchors และ custom theming ที่เว็บไซต์ของคุณจำเป็นต้องใช้กลับมาได้ แม้จะต้องใช้ความพยายามในช่วงเริ่มต้น แต่ผลตอบแทนที่ได้คือ markdown pipeline ที่รวดเร็วและคาดการณ์ผลลัพธ์ได้แม่นยำยิ่งขึ้น