Việc Astro 7 chuyển sang engine markdown Sätteri dựa trên Rust đang biến các khối display-math thành mã thuần túy, loại bỏ các heading anchors và hủy bỏ các tùy chọn markdown tùy chỉnh – một vấn đề gây khó chịu cho bất kỳ ai đã nâng cấp và hiện thấy các phương trình bị lỗi trên trang web của mình.
Nếu bạn dựa vào toán học kiểu LaTeX, các liên kết heading tự động hoặc các plugin markdown tùy chỉnh, việc nâng cấp có thể khiến nội dung của bạn không thể đọc được và điều hướng không thể sử dụng được, vì vậy việc khắc phục nhanh chóng là rất cần thiết.
Tại sao việc nâng cấp lại gây lỗi
Astro hiện chạy Sätteri như bộ xử lý Markdown cốt lõi của mình. Sätteri thay đổi thứ tự áp dụng các plugin: nó chạy syntax highlighting trước các plugin HTML-AST (HAST) mà bạn có thể đã cấu hình. Sự thay đổi đó có nghĩa là ba mô hình phổ biến sẽ ngừng hoạt động:
- Display math – các khối được phân tách bởi
$$ … $$bị coi là mã thông thường vì trình highlighter chạy trước. - Heading anchors – các plugin tạo slug (ID thân thiện với URL) và sau đó tự động liên kết (autolink) các heading đó không còn nhìn thấy các ID nữa, vì vậy các liên kết không bao giờ được tạo ra.
- Custom options – bất kỳ cài đặt bổ sung nào bạn truyền trực tiếp vào bộ xử lý Sätteri đều bị bỏ qua; Astro chỉ chuyển tiếp ba trường đã được định nghĩa trước.
Các cách khắc phục cụ thể
1. Render toán học trên markdown-AST (MDAST) thay vì HTML-AST
Pipeline markdown của Astro có hai vị trí (slot) plugin:
mdastPlugins– chạy trên cây markdown đã được phân tích trước khi nó trở thành HTML.hastPlugins– chạy trên cây HTML sau khi chuyển đổi.
Vì trình highlighter chạy trước hastPlugins, toán học bị biến thành một khối mã. Hãy chuyển plugin toán học của bạn sang mdastPlugins.
export default {
markdown: {
mdastPlugins: [
// put remark-math (or your custom math handler) here
],
// leave hastPlugins for things that truly need HTML nodes
}
}
2. Sắp xếp lại thứ tự các plugin slug và autolink cho heading
Các thiết lập tiêu chuẩn cài đặt một trình tạo slug, sau đó là một plugin autolink. Trong Astro, plugin heading-ID tích hợp sẵn chạy sau danh sách của bạn, khiến plugin autolink không còn gì để gắn vào. Hãy đặt plugin slug lên đầu danh sách, sau đó mới đến plugin autolink.
export default {
markdown: {
mdastPlugins: [
satteriSlug(), // must be first
satteriAutolinkHeadings() // runs after slug, sees IDs
]
}
}
Bây giờ mỗi heading sẽ nhận được một ID và plugin autolink có thể bao bọc nó bằng anchor thích hợp.
3. Đặt cấu hình bổ sung ở cấp cao nhất của đối tượng markdown Astro
Astro chỉ chuyển tiếp ba trường cụ thể đến bộ xử lý Sätteri. Bất cứ thứ gì bạn lồng bên trong bộ xử lý (ví dụ: một đối tượng shikiConfig) đều bị loại bỏ. Hãy chuyển các cài đặt bổ sung đó lên cấp cao nhất của cấu hình markdown.
export default {
markdown: {
shikiConfig: { theme: 'nord' }, // top-level, will be respected
// other Astro-accepted fields …
mdastPlugins: [/* … */],
hastPlugins: [/* … */]
}
}
Hướng dẫn thay thế nhanh cho các remark plugin phổ biến
| remark plugin cũ | Astro feature flag mới |
|---|---|
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 |
Thay thế tên plugin bằng flag features.* tương ứng trong cấu hình Astro của bạn.
Các thực hành tốt nhất khi chuyển đổi plugin sang Sätteri
- Factory pattern – tạo một instance plugin mới cho mỗi tài liệu để tránh rò rỉ trạng thái giữa các trang.
- Immutable nodes – không bao giờ thay đổi trực tiếp một node; hãy trả về một đối tượng node mới để bộ xử lý có thể theo dõi các thay đổi một cách chính xác.
- Insert helpers – sử dụng
ctx.insertBeforehoặcctx.insertAfterkhi bạn cần thêm các node anh em (sibling nodes), thay vì cắt ghép (splicing) cây một cách thủ công.
Tuân thủ các quy tắc này giúp bộ xử lý hoạt động ổn định và ngăn ngừa các lỗi khó theo dõi.
Những điều cần lưu ý tiếp theo
Tài liệu của Astro vẫn liệt kê thứ tự plugin cũ là mặc định, vì vậy các dự án mới có thể vô tình gặp phải hành vi lỗi này. Hãy theo dõi các bản phát hành Astro sắp tới để tìm kiếm một bản sửa lỗi tích hợp có thể sắp xếp lại plugin heading-ID nội bộ. Trong thời gian chờ đợi, các bước trên là cách đáng tin cậy duy nhất để khôi phục việc hiển thị toán học, heading anchors và các tùy chọn markdown tùy chỉnh sau khi chuyển sang Astro 7.
Tóm tắt: Việc chuyển sang engine Sätteri của Astro 7 yêu cầu chuyển việc xử lý toán học sang mdastPlugins, đưa plugin slug lên trước các autolinks, và đưa bất kỳ cài đặt markdown bổ sung nào ra khỏi đối tượng bộ xử lý; một khi thực hiện ba điều chỉnh này, các phương trình, liên kết điều hướng và các tính năng markdown tùy chỉnh trên trang web của bạn sẽ hoạt động như trước.