Naik Taraf Astro 7 Menjejaskan Matematik, Pautan Tajuk dan Pilihan Tersuai – Cara Memperbaikinya

Peralihan Astro 7 kepada enjin markdown Sätteri berasaskan Rust menukarkan blok display-math kepada kod biasa, membuang sauh tajuk (heading anchors) dan mengabaikan pilihan markdown tersuai – satu masalah besar bagi sesiapa yang telah menaik taraf dan kini melihat persamaan yang rosak pada laman web mereka.

Jika anda bergantung pada matematik gaya LaTeX, pautan tajuk automatik atau plugin markdown tersuai, peningkatan tersebut boleh menyebabkan kandungan anda tidak dapat dibaca dan navigasi anda tidak boleh digunakan, jadi memperbaikinya dengan cepat adalah sangat penting.

Mengapa peningkatan tersebut merosakkan segalanya

Astro kini menjalankan Sätteri sebagai pemproses Markdown terasnya. Sätteri mengubah urutan aplikasi plugin: ia menjalankan penonjolan sintaks (syntax highlighting) sebelum plugin HTML-AST (HAST) yang mungkin telah anda konfigurasi. Peralihan itu bermakna tiga corak biasa tidak lagi berfungsi:

• Display math – blok yang dibatasi oleh $$ … $$ dianggap sebagai kod biasa kerana penonjol (highlighter) dijalankan terlebih dahulu.
• Heading anchors – plugin yang menjana slug (ID mesra URL) dan kemudian membuat pautan automatik (autolink) pada tajuk tersebut tidak lagi dapat melihat ID tersebut, jadi pautan tidak akan dicipta.
• Custom options – sebarang tetapan tambahan yang anda hantar terus ke dalam pemproses Sätteri akan diabaikan; Astro hanya memanjangkan tiga medan yang telah ditetapkan.

Langkah pembaikan konkrit

1. Render matematik pada markdown-AST (MDAST) dan bukannya HTML-AST

Saluran (pipeline) markdown Astro mempunyai dua slot plugin:

• mdastPlugins – dijalankan pada pokok markdown yang telah diurai sebelum ia menjadi HTML.
• hastPlugins – dijalankan pada pokok HTML selepas penukaran.

Oleh kerana penonjol dijalankan sebelum hastPlugins, matematik akan ditukarkan menjadi blok kod. Pindahkan plugin matematik anda ke mdastPlugins.

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

2. Susun semula urutan plugin slug dan autolink untuk tajuk

Tetapan standard memasang penjana slug diikuti oleh plugin autolink. Dalam Astro, plugin heading-ID terbina dalam dijalankan selepas senarai anda, menyebabkan tiada apa yang tinggal untuk plugin autolink pautkan. Letakkan plugin slug sebagai yang pertama dalam senarai, kemudian plugin autolink.

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

Kini setiap tajuk menerima ID dan plugin autolink boleh membungkusnya dengan sauh (anchor) yang sesuai.

3. Letakkan konfigurasi tambahan pada tahap teratas objek markdown Astro

Astro hanya memanjangkan tiga medan khusus ke pemproses Sätteri. Apa-apa sahaja yang anda sarangkan (nest) di dalam pemproses (contohnya objek shikiConfig) akan dibuang. Pindahkan tetapan tambahan tersebut ke tahap teratas konfigurasi markdown.

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

Panduan penggantian pantas untuk plugin remark yang biasa digunakan

Plugin remark lama	Flag ciri Astro baharu
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

Tukar nama plugin dengan flag features.* yang sepadan dalam konfigurasi Astro anda.

Amalan terbaik semasa memindahkan plugin ke Sätteri

• Factory pattern – cipta instans plugin baharu bagi setiap dokumen untuk mengelakkan kebocoran keadaan (state) antara halaman.
• Immutable nodes – jangan sesekali mengubah suai nod di tempatnya (in place); pulangkan objek nod baharu supaya pemproses dapat menjejaki perubahan dengan betul.
• Insert helpers – gunakan ctx.insertBefore atau ctx.insertAfter apabila anda perlu menambah nod adik-beradik (sibling nodes), daripada melakukan splicing pada pokok secara manual.

Mengikuti peraturan ini memastikan pemproses kekal stabil dan mengelakkan pepijat yang sukar dikesan.

Apa yang perlu diperhatikan seterusnya

Dokumentasi Astro masih menyenaraikan urutan plugin lama sebagai lalai, jadi projek baharu mungkin mewarisi tingkah laku yang rosak secara tidak sengaja. Perhatikan pelancaran Astro akan datang untuk kemungkinan pembaikan terbina dalam yang menyusun semula plugin heading-ID dalaman. Sementara itu, langkah-langkah di atas adalah satu-satunya cara yang boleh dipercayai untuk memulihkan paparan matematik, sauh tajuk dan pilihan markdown tersuai selepas berpindah ke Astro 7.

Rumusan: Peralihan ke enjin Sätteri Astro 7 memerlukan pemindahan pengendalian matematik ke mdastPlugins, meletakkan plugin slug di hadapan sebelum autolink, dan mengeluarkan sebarang tetapan markdown tambahan daripada objek pemproses; sebaik sahaja tiga pelarasan tersebut dibuat, persamaan, pautan navigasi dan ciri markdown tersuai laman web anda akan berfungsi seperti sediakala.