refactor: Markdown 管线迁移到 Sätteri(Phase 1 + Phase 2)

把 markdown.processor 从 unified() 换成 Astro 7 的默认管线 satteri(),
并把原来 12 个 remark/rehype 插件逐一移植到 Sätteri 的 MDAST/HAST 插件模型。

内置能力直接替代(零代码)
- remark-math      → features.math
- remark-directive → 未启用(见下)
- rehype-slug      → satteriHeadingIdsPlugin()

新增 src/plugins/satteri/(6 个插件,约 200 行)
- reading-time.mjs    after 钩子写 ctx.data.astro.frontmatter.minutes/words
- excerpt.mjs         取第一段写 frontmatter.excerpt
- shift-headings.mjs  工厂按 fileURL 判断,只对 posts 下的文章生效
- sectionize.mjs      remark-sectionize 的等价实现(递归分组 + data.hName)
- autolink-headings.mjs  标题锚点,输出与 rehype-autolink-headings 逐字一致
- image-lightbox.mjs  上一版 rehype 图片灯箱的 HAST 版

删除(已迁移或本就无效)
- remark-reading-time / remark-excerpt / remark-shift-headings /
  remark-directive-rehype / rehype-component-admonition /
  rehype-image-lightbox —— 共 6 个旧插件文件
- 未启用 features.directive:内容里的 `::: tip`(冒号后有空格)和
  `> [!tip] Tip` 在迁移前后都渲染成普通段落/引用,属于死语法;
  保持现状以免升级顺手把它激活。

行为对齐
- smartPunctuation: { dashes: false } —— Astro 的 unified 管线会把直引号
  排成弯引号但不转换 ---,Sätteri 默认会转,显式关掉 dashes 才能逐字一致。

验证(与 unified() 构建逐页对比,41 页)
- 正文 HTML 完全一致 35 页;把 HTML 实体和表格对齐写法归一化后,
  只剩 3 页有差异:1 页是 KaTeX 尚未迁移(见下),2 页是中文/emoji 旁的
  引号方向(Sätteri 的结果更正确)。
- meta description 仍由 excerpt 正确生成;阅读时长与基线一致。
- astro check:1 error / 0 warnings,与迁移前完全相同(原有 footer.astro 报错)。
- pnpm build 41 页通过;dev server 正常。

尚未迁移
- KaTeX:Sätteri 的 math 只负责解析,不渲染。数学公式目前落成
  <code class="language-math">,是可见的回归,Phase 3 处理。
- package.json 里 remark-*/rehype-* 依赖暂未清理,等 Phase 3 确定后再收。
This commit is contained in:
2026-09-17 17:38:37 +08:00
parent c1643ae95d
commit 26e873b9f6
16 changed files with 248 additions and 237 deletions
+24 -69
View File
@@ -5,30 +5,17 @@ import mdx from "@astrojs/mdx"
import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections"
import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers"
import expressiveCode from "astro-expressive-code"
import rehypeAutolinkHeadings from "rehype-autolink-headings"
import rehypeComponents from "rehype-components"
import rehypeKatex from "rehype-katex"
import rehypeSlug from "rehype-slug"
import remarkDirective from "remark-directive"
import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives"
import remarkMath from "remark-math"
import remarkSectionize from "remark-sectionize"
import { remarkShiftHeadings } from "./src/plugins/remark-shift-headings.mjs"
import { AdmonitionComponent } from "./src/plugins/rehype-component-admonition.mjs"
import { parseDirectiveNode } from "./src/plugins/remark-directive-rehype.js"
import { remarkExcerpt } from "./src/plugins/remark-excerpt.js"
import { remarkReadingTime } from "./src/plugins/remark-reading-time.mjs"
import { pluginLanguageBadge } from "./src/plugins/expressive-code/language-badge"
import { pluginCustomCopyButton } from "./src/plugins/expressive-code/custom-copy-button"
import { unified } from "@astrojs/markdown-remark"
import { rehypeImageLightbox } from "./src/plugins/rehype-image-lightbox.mjs"
import { satteri, satteriHeadingIdsPlugin } from "@astrojs/markdown-satteri"
import { excerpt } from "./src/plugins/satteri/excerpt.mjs"
import { readingTime } from "./src/plugins/satteri/reading-time.mjs"
import { sectionize } from "./src/plugins/satteri/sectionize.mjs"
import { shiftHeadings } from "./src/plugins/satteri/shift-headings.mjs"
import { autolinkHeadings } from "./src/plugins/satteri/autolink-headings.mjs"
import { imageLightbox } from "./src/plugins/satteri/image-lightbox.mjs"
import { site } from "./src/data/site"
const createAdmonitionComponent = (type) => (properties = {}, children = []) => {
const normalizedChildren = Array.isArray(children) ? children : []
return AdmonitionComponent(properties, normalizedChildren, type)
}
export default defineConfig({
srcDir: "./src",
output: "static",
@@ -88,56 +75,24 @@ export default defineConfig({
],
compressHTML: true,
markdown: {
processor: unified({
remarkPlugins: [
remarkMath,
remarkReadingTime,
remarkExcerpt,
remarkShiftHeadings,
remarkGithubAdmonitionsToDirectives,
remarkDirective,
remarkSectionize,
parseDirectiveNode,
// Astro 7 的 Sätteri 管线。以下插件是 unified 时期 remark/rehype 插件的对应移植,
// 见 src/plugins/satteri/。
//
// 注意:math 只负责「解析」,渲染成 KaTeX 需要额外的 HAST 插件 —— 尚未迁移。
processor: satteri({
// dashes: false 是为了和迁移前的输出逐字一致:Astro 的 unified 管线
// 会把直引号排成弯引号,但不转换 --- (Sätteri 默认会转成破折号)。
features: { math: true, smartPunctuation: { dashes: false } },
mdastPlugins: [
readingTime,
excerpt,
shiftHeadings(),
sectionize(),
],
rehypePlugins: [
rehypeKatex,
rehypeSlug,
[
rehypeComponents,
{
components: {
note: createAdmonitionComponent("note"),
tip: createAdmonitionComponent("tip"),
important: createAdmonitionComponent("important"),
caution: createAdmonitionComponent("caution"),
warning: createAdmonitionComponent("warning"),
},
},
],
[
rehypeAutolinkHeadings,
{
behavior: "append",
properties: {
className: ["anchor"],
},
content: {
type: "element",
tagName: "span",
properties: {
className: ["anchor-icon"],
"data-pagefind-ignore": true,
},
children: [
{
type: "text",
value: "#",
},
],
},
},
],
rehypeImageLightbox,
hastPlugins: [
satteriHeadingIdsPlugin(),
autolinkHeadings,
imageLightbox,
],
}),
},