Pembaruan Astro 7 Merusak Matematika, Tautan Heading, dan Opsi Kustom – Cara Memperbaikinya

Peralihan Astro 7 ke mesin markdown Sätteri berbasis Rust mengubah blok display-math menjadi kode biasa, menghilangkan anchor heading, dan membuang opsi markdown kustom – sebuah masalah bagi siapa pun yang telah melakukan upgrade dan kini melihat persamaan yang rusak di situs mereka.

Jika Anda bergantung pada math gaya LaTeX, tautan heading otomatis, atau plugin markdown khusus, upgrade ini dapat membuat konten Anda tidak terbaca dan navigasi Anda tidak dapat digunakan, sehingga memperbaikinya dengan cepat sangatlah penting.

Mengapa upgrade merusak segalanya

Astro kini menjalankan Sätteri sebagai prosesor Markdown intinya. Sätteri mengubah urutan penerapan plugin: ia menjalankan syntax highlighting sebelum plugin HTML-AST (HAST) yang mungkin telah Anda konfigurasi. Perubahan tersebut menyebabkan tiga pola umum berhenti berfungsi:

• Display math – blok yang dibatasi oleh $$ … $$ diperlakukan sebagai kode biasa karena highlighter berjalan lebih dulu.
• Heading anchors – plugin yang menghasilkan slug (ID yang ramah URL) dan kemudian melakukan autolink pada heading tersebut tidak lagi dapat melihat ID-nya, sehingga tautan tidak pernah dibuat.
• Custom options – pengaturan tambahan apa pun yang Anda masukkan langsung ke dalam prosesor Sätteri akan diabaikan; Astro hanya meneruskan tiga field yang telah ditentukan sebelumnya.

Perbaikan konkret

1. Render math pada markdown-AST (MDAST) alih-alih HTML-AST

Pipeline markdown Astro memiliki dua slot plugin:

• mdastPlugins – dijalankan pada pohon markdown yang telah di-parse sebelum menjadi HTML.
• hastPlugins – dijalankan pada pohon HTML setelah konversi.

Karena highlighter berjalan sebelum hastPlugins, math diubah menjadi blok kode. Pindahkan plugin math 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. Atur ulang urutan plugin slug dan autolink untuk heading

Pengaturan standar menginstal generator slug yang diikuti oleh plugin autolink. Di Astro, plugin heading-ID bawaan berjalan setelah daftar Anda, sehingga tidak ada yang tersisa untuk ditempelkan oleh plugin autolink. Letakkan plugin slug di urutan pertama dalam daftar, kemudian plugin autolink.

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

Sekarang setiap heading menerima ID dan plugin autolink dapat membungkusnya dengan anchor yang sesuai.

3. Letakkan konfigurasi tambahan di level teratas objek markdown Astro

Astro hanya meneruskan tiga field spesifik ke prosesor Sätteri. Apa pun yang Anda sarangkan di dalam prosesor (misalnya objek shikiConfig) akan dibuang. Pindahkan pengaturan tambahan tersebut ke level teratas konfigurasi markdown.

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

Panduan penggantian cepat untuk plugin remark yang umum

Plugin remark lama	Flag fitur Astro baru
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

Ganti nama plugin dengan flag features.* yang sesuai di konfigurasi Astro Anda.

Praktik terbaik saat memindahkan plugin ke Sätteri

• Factory pattern – buat instance plugin baru per dokumen untuk menghindari kebocoran state antar halaman.
• Immutable nodes – jangan pernah mengubah node secara langsung; kembalikan objek node baru agar prosesor dapat melacak perubahan dengan benar.
• Insert helpers – gunakan ctx.insertBefore atau ctx.insertAfter saat Anda perlu menambahkan node sibling, daripada melakukan splicing pada pohon secara manual.

Mengikuti aturan ini menjaga prosesor tetap stabil dan mencegah bug yang sulit dilacak.

Apa yang perlu diperhatikan selanjutnya

Dokumentasi Astro masih mencantumkan urutan plugin lama sebagai default, sehingga proyek baru mungkin mewarisi perilaku yang rusak secara tidak sengaja. Pantau rilis Astro mendatang untuk kemungkinan perbaikan bawaan yang mengatur ulang plugin heading-ID internal. Sementara itu, langkah-langkah di atas adalah satu-satunya cara andal untuk memulihkan rendering math, anchor heading, dan opsi markdown kustom setelah pindah ke Astro 7.

Kesimpulan: Beralih ke mesin Sätteri di Astro 7 memerlukan pemindahan penanganan math ke mdastPlugins, mendahulukan plugin slug sebelum autolink, dan mengeluarkan pengaturan markdown tambahan dari objek prosesor; setelah ketiga penyesuaian tersebut dilakukan, persamaan, tautan navigasi, dan fitur markdown kustom di situs Anda akan berfungsi seperti sebelumnya.