Peralihan Astro 7 kepada enjin markdown Sätteri berasaskan Rust telah mengubah naik taraf yang sepatutnya lancar menjadi mimpi ngeri tiga kali ganda bagi laman web yang bergantung pada matematik, sauh tajuk (heading anchors), dan konfigurasi tersuai. Persamaan dalam baris (inline equations) masih berfungsi, tetapi blok matematik paparan (display-math blocks) muncul sebagai petikan kod teks biasa, ID tajuk hilang, dan sebarang pilihan tambahan yang anda masukkan ke dalam konfigurasi Astro akan diabaikan secara senyap. Pembangun yang berpindah daripada versi Astro terdahulu kini perlu menulis semula plugin atau berisiko menghadapi halaman yang rosak.

Mengapa perubahan ini penting

Enjin baharu ini menjalankan penyerlah sintaks (syntax highlighter) terbina dalam sebelum sebarang plugin yang dibekalkan pengguna dan hanya menerima tiga medan konfigurasi peringkat teratas. Pilihan tersebut bercanggah dengan cara kebanyakan projek Astro menambah ciri: melalui plugin remark (MDAST) dan rehype (HAST) yang dijangka berjalan selepas penyerlahan, dan melalui objek konfigurasi permisif yang dihantar terus ke parser markdown asas.

Kesan buruk ini muncul pada mana-mana halaman yang mencampurkan matematik gaya LaTeX dengan kandungan biasa. Matematik dalam baris ($a+b$) dipaparkan dengan baik, tetapi blok paparan ($$a+b$$) dibungkus dalam tag <pre>, menunjukkan markup mentah dan bukannya persamaan yang diformat. Sauh tajuk yang memacu pautan jadual kandungan atau pautan mendalam (deep-linking) hilang kerana plugin penjanaan ID berjalan sebelum pengendali ID terbina dalam, menyebabkan tiada apa yang boleh dicapai oleh plugin autolink. Pembangun yang cuba memperhalusi penyerlah sintaks Shiki dengan objek shikiConfig mendapati tetapan tersebut hilang tanpa kesan.

Pembaikan teknikal

1. Render matematik sebelum penyerlahan

Punca utamanya ialah urutan operasi: penyerlah Sätteri menuntut teks terlebih dahulu, mengklasifikasikan blok matematik sebagai kod biasa. Untuk mendapatkan semula matematik tersebut, alihkan pemprosesan ke lapisan MDAST (pokok sintaks abstrak yang mewakili markdown sebelum ia menjadi HTML). Gantikan mana-mana plugin matematik tahap HAST dengan setara MDAST mereka dan jalankannya sebelum langkah penyerlahan. Secara praktikal, tukar plugin remark-math kepada versi yang menyambung ke peringkat parsing markdown, kemudian biarkan penyerlah bekerja pada nod matematik yang telah ditukar.

2. Susun semula plugin ID tajuk

ID tajuk dijana oleh plugin terbina dalam yang kini dilaksanakan selepas plugin pengguna. Pindahkan penjana ID atau slug tersuai ke bahagian atas senarai plugin supaya ia berjalan terlebih dahulu. Urutan tipikal yang memulihkan pautan sauh adalah seperti berikut:

  1. plugin slug/ID
  2. plugin autolink
  3. sebarang plugin remark lain

Dengan ID yang tersedia lebih awal, plugin autolink boleh menyertakan elemen <a> yang diharapkan, dan jadual kandungan akan merujuk ke bahagian yang betul.

3. Patuhi skema konfigurasi ketat Sätteri

Sätteri hanya mengiktiraf tiga medan dalam konfigurasi markdown Astro. Apa-apa sahaja yang lain, seperti shikiConfig, akan digugurkan secara senyap. Untuk mengekalkan tema tersuai atau pelarasan penyerlah, pindahkan tetapan tersebut ke tahap yang betul dalam hierarki konfigurasi Astro.

Panduan penggantian pantas

Jika anda sedang memindahkan stack markdown Astro klasik, gantikan plugin remark lama dengan bendera ciri (feature flags) baharu yang difahami oleh Sätteri:

  • 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

Bendera ini membolehkan keupayaan yang sama tanpa memerlukan pemuatan plugin yang berasingan.

Peraturan untuk memastikan plugin serasi dengan Sätteri

  • Hanya satu laluan (Single pass only) – Plugin hanya melihat pokok sekali; ia tidak boleh melawat semula nod yang dicipta kemudian dalam saluran paip (pipeline).
  • Kilang untuk keadaan (Factory for state) – Bina objek keadaan (state object) yang baharu untuk setiap halaman bagi mengelakkan kebocoran data antara halaman.
  • Nod tidak boleh diubah (Immutable nodes) – Pulangkan nod baharu apabila anda memerlukan perubahan; mengubah suai nod sedia ada boleh merosakkan langkah pemprosesan seterusnya.
  • Tiada fragmen akar (No root fragments) – Masukkan adik-beradik (siblings) melalui pembantu penyisipan yang disediakan dan bukannya mencipta nod fragmen peringkat teratas.

Apabila anda menyesuaikan plugin sedia ada, jangan bergantung pada output contoh dalam README. Render HTML plugin asal, tangkap markup tersebut, dan gunakannya sebagai titik rujukan untuk versi serasi Sätteri anda.

Rumusan

Enjin Sätteri Astro 7 membawa kepantasan tetapi memaksa penyusunan semula rantaian pemprosesan markdown: render math pada tahap MDAST, letakkan plugin heading-ID di bahagian hadapan, dan hadkan konfigurasi kepada tiga medan yang diterima. Ikuti pemetaan feature-flag, patuhi peraturan single-pass dan immutable-node, dan anda akan memulihkan math, anchor, serta custom theming yang diperlukan oleh laman web anda. Usaha ini perlu dilakukan di peringkat awal; hasilnya adalah pipeline markdown yang lebih boleh diramal dan lebih pantas.