Sửa Cảnh Báo markdown.remarkPlugins Deprecated Trong Astro

Cảnh Báo Deprecation Là Gì?#

Khi khởi động máy chủ phát triển (astro dev) hoặc build dự án (astro build), bạn có thể bắt gặp dòng cảnh báo màu vàng sau trong terminal:

[astro] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` are deprecated. Pass them to `unified({...})` from `@astrojs/markdown-remark` directly instead.

Nếu dự án của bạn đang sử dụng các plugin Remark hoặc Rehype (ví dụ như remark-math, rehype-katex, rehypeHeadingIds hay rehype-autolink-headings), Astro đang thông báo rằng cách cấu hình ở cấp độ gốc (root-level) của markdown đã lỗi thời và sẽ bị gỡ bỏ để chuyển sang kiến trúc bộ xử lý Markdown riêng biệt (markdown.processor).

Hãy cùng tìm hiểu nguyên nhân sự thay đổi này, cách hoạt động của hệ thống mới và cách cập nhật cấu hình chỉ trong vòng 2 phút.

Tại Sao Astro Thay Đổi API Markdown?#

Giải Thích Đơn Giản (ELI5)#

Hãy tưởng tượng Astro giống như một gian bếp hiện đại:

• Trước đây: Astro chỉ gắn cố định một chiếc lò nướng duy nhất (engine Unified/Remark/Rehype) vào thẳng tường bếp. Nếu bạn muốn gắn thêm phụ kiện hay cài đặt nhiệt độ (các plugin), bạn phải cắm trực tiếp vào bảng điện chung của nhà bếp (markdown.remarkPlugins).
• Hiện tại: Astro đã thiết kế lại một khe cắm lò nướng linh hoạt (markdown.processor).
  • Bạn có thể cắm chiếc lò nướng Unified (@astrojs/markdown-remark) nếu muốn tận dụng hệ sinh thái phong phú với hàng trăm plugin Remark/Rehype.
  • Hoặc cắm chiếc lò nướng Sätteri siêu tốc (@astrojs/markdown-satteri) viết bằng ngôn ngữ Rust để tối ưu hóa tốc độ build cực nhanh.

Vì các plugin Remark và Rehype chỉ dành riêng cho engine Unified, việc khai báo chúng ở ngoài cấu hình tổng thể của Astro không còn hợp lý về mặt kiến trúc. Astro yêu cầu bạn truyền các plugin trực tiếp vào bộ xử lý unified({...}).

flowchart TD
    subgraph Legacy["Kiến Trúc Cũ (Legacy Architecture)"]
        L_Config["astro.config.mjs (markdown.remarkPlugins / rehypePlugins)"] --> L_Engine["Astro Core (Unified Parser Cố Định)"]
    end

    subgraph Modern["Kiến Trúc Mới Trong Astro (v6.4+ / v7+)"]
        M_Config["astro.config.mjs (markdown.processor)"]
        M_Config --> M_Choice{"Lựa Chọn Bộ Xử Lý (Processor)"}
        M_Choice -->|unified: remarkPlugins, rehypePlugins| M_Unified["@astrojs/markdown-remark (Unified / Remark / Rehype)"]
        M_Choice -->|satteri: mdastPlugins, hastPlugins| M_Satteri["@astrojs/markdown-satteri (Sätteri Engine bằng Rust)"]
    end

Những Lợi Ích Của Kiến Trúc Mới#

1. Tách rời bộ parser: Core của Astro nhẹ hơn vì không bị phụ thuộc cứng vào hệ sinh thái Unified.
2. Hỗ trợ compiler Rust: Từ Astro v7+, Sätteri trở thành processor mặc định không cần cấu hình, đem lại tốc độ xử lý vượt trội.
3. Phạm vi cấu hình rõ ràng: Các tùy chọn của từng engine (remarkPlugins, rehypePlugins, gfm, smartypants) nằm trọn vẹn bên trong định nghĩa của processor đó.

Hướng Dẫn Sửa Chi Tiết Từng Bước#

Bước 1: Cài đặt @astrojs/markdown-remark#

Đảm bảo gói chính thức @astrojs/markdown-remark đã có mặt trong dự án của bạn:

bun add @astrojs/markdown-remark
# hoặc
npm install @astrojs/markdown-remark
# hoặc
pnpm add @astrojs/markdown-remark

Bước 2: Cập nhật astro.config.ts (hoặc astro.config.mjs)#

Import hàm unified từ @astrojs/markdown-remark và chuyển các plugin vào trong processor: unified({...}):

import { defineConfig } from 'astro/config';
import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [[rehypeKatex, {}], rehypeHeadingIds],
    smartypants: true,
    processor: unified({
      remarkPlugins: [remarkMath],
      rehypePlugins: [
        [rehypeKatex, {}],
        rehypeHeadingIds,
      ],
      gfm: true,
      smartypants: true,
    }),
    // Syntax highlighting vẫn giữ nguyên ở cấp markdown
    shikiConfig: {
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
  },
});

[!NOTE] Lưu ý rằng cấu hình highlight code shikiConfig vẫn nằm trực tiếp trong markdown: { ... }. Chỉ những tùy chọn phân tích Markdown (remarkPlugins, rehypePlugins, remarkRehype, gfm, smartypants) mới chuyển vào processor: unified({ ... }).

Các Tùy Chọn Phổ Biến Trong unified({...})#

Bảng tóm tắt các tùy chọn bạn có thể thiết lập trực tiếp trong unified({...}):

Ví dụ: Tùy Biến Chú Thích Cuối Trang (Footnotes)#

Nếu bạn từng cấu hình chú thích thông qua markdown.remarkRehype, hãy chuyển vào unified({...}):

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkRehype: {
        footnoteBackContent: '↩',
        footnoteLabel: 'Chú thích',
      },
    }),
  },
});

Lựa Chọn Khác: Sử Dụng Bộ Xử Lý Sätteri (Rust)#

Nếu trang web của bạn không cần các plugin Remark/Rehype phức tạp và muốn tốc độ build nhanh nhất có thể, bạn có thể chuyển sang dùng Sätteri:

bun add @astrojs/markdown-satteri

Sau đó khai báo trong astro.config.ts:

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        gfm: true,
        smartPunctuation: true,
      },
    }),
  },
});

[!TIP] Sätteri sử dụng mdastPlugins và hastPlugins được viết riêng theo chuẩn AST của nó thay vì các gói remark/rehype trên npm. Nếu bạn cần các plugin phổ biến như remark-math hay rehype-katex, hãy tiếp tục sử dụng processor: unified({...}).

Tương Thích Với Các Third-Party Integrations#

Các thư viện tích hợp như astro-mermaid, @astrojs/mdx hay các plugin cộng đồng đều tự động kiểm tra config.markdown.processor. Khi bạn cấu hình processor: unified({...}), các integration này sẽ tự động gắn thêm các bộ biến đổi vào pipeline của bạn mà không hề xung đột.

bun run check
bun run build

Sau khi hoàn tất, terminal của bạn sẽ sạch sẽ và không còn bất kỳ dòng cảnh báo deprecation nào.

Tổng Kết#

• Vấn đề: Astro đã deprecate cấu hình cấp ngoài markdown.remarkPlugins, markdown.rehypePlugins và markdown.remarkRehype.
• Cách giải quyết: Đưa toàn bộ plugin vào trong markdown.processor: unified({ remarkPlugins: [...], rehypePlugins: [...] }) từ @astrojs/markdown-remark.
• Lưu ý: shikiConfig vẫn giữ ở cấp độ markdown, chỉ có các parser options mới chuyển vào unified({...}).

Tài Liệu Tham Khảo#

• Astro Documentation — Markdown in Astro ↗
• Astro Configuration Reference — markdown.processor ↗
• @astrojs/markdown-remark Package trên npm ↗
• Tài Liệu Sätteri ↗
• Trang Chủ Unified.js ↗