Astro 7 切换到基于 Rust 的 Sätteri Markdown 引擎后，会将 display-math 块转换为普通代码，剥离标题锚点并丢弃自定义 Markdown 选项——对于任何升级后发现网站公式显示异常的用户来说，这都是一个痛点。
如果你依赖 LaTeX 风格的数学公式、自动标题链接或自定义 Markdown 插件，此次升级可能会导致内容无法阅读且导航失效，因此快速修复至关重要。
为什么升级会导致问题
Astro 现在将 Sätteri 作为其核心 Markdown 处理器运行。Sätteri 改变了插件的应用顺序：它会在你配置的 HTML-AST (HAST) 插件之前运行语法高亮。这种转变意味着三种常见模式将失效：
- Display math – 由于高亮器先运行，由
$$ … $$分隔的块会被视为普通代码。 - Heading anchors – 生成 slug（URL 友好的 ID）并随后自动链接这些标题的插件将无法识别这些 ID，因此链接无法创建。
- Custom options – 你直接传递给 Sätteri 处理器的任何额外设置都会被忽略；Astro 仅转发三个预定义字段。
具体修复方案
1. 在 markdown-AST (MDAST) 而非 HTML-AST 上渲染数学公式
Astro 的 Markdown 流水线有两个插件插槽：
mdastPlugins– 在解析后的 Markdown 树转换为 HTML 之前运行。hastPlugins– 在转换后的 HTML 树上运行。
由于高亮器在 hastPlugins 之前运行，数学公式会被转换为代码块。请将你的数学插件移至 mdastPlugins。
export default {
markdown: {
mdastPlugins: [
// put remark-math (or your custom math handler) here
],
// leave hastPlugins for things that truly need HTML nodes
}
}
2. 重新排列标题的 slug 和 autolink 插件
标准配置通常先安装 slug 生成器，随后安装 autolink 插件。在 Astro 中，内置的 heading-ID 插件是在你的列表之后运行的，导致 autolink 插件无法找到可附加的对象。请将 slug 插件放在列表的首位，然后是 autolink 插件。
export default {
markdown: {
mdastPlugins: [
satteriSlug(), // must be first
satteriAutolinkHeadings() // runs after slug, sees IDs
]
}
}
现在每个标题都会获得一个 ID，autolink 插件可以为其包裹适当的锚点。
3. 将额外配置放在 Astro markdown 对象的顶层
Astro 仅向 Sätteri 处理器转发三个特定字段。任何嵌套在处理器内部的设置（例如 shikiConfig 对象）都会被丢弃。请将这些额外设置移至 markdown 配置的顶层。
export default {
markdown: {
shikiConfig: { theme: 'nord' }, // top-level, will be respected
// other Astro-accepted fields …
mdastPlugins: [/* … */],
hastPlugins: [/* … */]
}
}
常用 remark 插件快速替换指南
| 旧 remark 插件 | 新 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 |
在你的 Astro 配置中，将插件名称替换为对应的 features.* 标志。
将插件移植到 Sätteri 时的最佳实践
- Factory pattern – 为每个文档创建一个新的插件实例，以避免页面间的状态泄露。
- Immutable nodes – 永远不要原地修改节点；返回一个新的节点对象，以便处理器能够正确跟踪更改。
- Insert helpers – 当需要添加兄弟节点时，请使用
ctx.insertBefore或ctx.insertAfter，而不是手动对树进行切片 (splicing)。
遵循这些规则可以保持处理器的稳定性，并防止难以追踪的 bug。
后续关注事项
Astro 的文档仍将旧的插件顺序列为默认设置，因此新项目可能会无意中继承这种损坏的行为。请留意后续的 Astro 版本，可能会有重新排列内部 heading-ID 插件顺序的内置修复。在此期间，上述步骤是迁移到 Astro 7 后恢复数学公式渲染、标题锚点和自定义 Markdown 选项的唯一可靠方法。
核心要点： 切换到 Astro 7 的 Sätteri 引擎需要将数学处理移至 mdastPlugins，在 autolinks 之前前置 slug 插件，并将任何额外的 Markdown 设置从处理器对象中提取到顶层；完成这三项调整后，你网站的公式、导航链接和自定义 Markdown 功能将恢复正常。