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

Astro 7 的 Sätteri 引擎带来了速度提升，但也迫使 Markdown 处理链需要重新排序：在 MDAST 层级渲染数学公式，将标题 ID 插件置于前端，并将配置限制在三个允许的字段内。遵循特性标志映射，遵守单次处理和不可变节点规则，你就能恢复网站所依赖的数学公式、锚点和自定义主题。虽然前期需要投入精力，但回报是一个更可预测、更快速的 Markdown 流水线。