@astrojs/markdown-remark — Xử Lý Markdown Trong Astro • blog.dopana

Nếu bạn từng xây dựng blog, trang tài liệu (documentation), hoặc portfolio bằng Astro, chắc chắn bạn đã biết framework này hỗ trợ tệp .md tốt đến mức nào. Nhưng bạn có bao giờ tự hỏi điều gì diễn ra phía sau hậu trường khi Astro biến những dòng mã Markdown thô kệch thành các trang HTML tĩnh đẹp mắt và tối ưu SEO?

Câu trả lời chính là @astrojs/markdown-remark — gói thư viện cốt lõi (core package) vận hành toàn bộ hệ thống xử lý nội dung của Astro.

Trong bài viết này, chúng ta sẽ cùng mổ xẻ xem @astrojs/markdown-remark là gì, cách nó hoạt động và làm thế nào để làm chủ sức mạnh của nó nhằm tùy biến website theo ý muốn.

1. @astrojs/markdown-remark Là Gì?#

@astrojs/markdown-remark là một package nội bộ được tích hợp sẵn trong Astro. Nhiệm vụ duy nhất nhưng tối quan trọng của nó là: Phân tích cú pháp (parse), biến đổi và biên dịch các tệp Markdown thành mã HTML.

Thay vì tự xây dựng một trình biên dịch từ đầu, Astro đứng trên vai những người khổng lồ. Gói này tích hợp hệ sinh thái Unified, cụ thể là:

Remark: Trình biên dịch để chuyển đổi nội dung Markdown thành cấu trúc cây cú pháp trừu tượng (MDast — Markdown Abstract Syntax Tree).
Rehype: Trình biên dịch làm việc với HTML (HAST — HTML Abstract Syntax Tree) để tối ưu hóa và xuất ra mã HTML cuối cùng.

Khi bạn chạy lệnh bun run build hoặc sử dụng Content Collections, Astro sẽ âm thầm gọi @astrojs/markdown-remark để xử lý các tệp nội dung của bạn.

2. Các Tính Năng Cốt Lõi Vận Hành Website Của Bạn#

Mặc dù hoạt động ngầm, gói thư viện này cung cấp những tính năng nền tảng mà bạn sử dụng hàng ngày:

Trích xuất Frontmatter (Metadata)#

Mỗi bài viết Markdown thường bắt đầu bằng đoạn mã YAML như:

---
title: 'Bài viết đầu tiên'
pubDate: 2026-07-26
author: 'Astro Developer'
---

yaml

@astrojs/markdown-remark chịu trách nhiệm bóc tách phần này, chuyển nó thành một object JavaScript để bạn dễ dàng truyền vào Layout hoặc các component của Astro dưới dạng {frontmatter}.

Tích hợp sẵn Shiki và Prism để Highlight Code#

Bạn có bao giờ thắc mắc tại sao các khối mã (code block) trong bài viết của bạn lại tự động có màu sắc bắt mắt? Gói thư viện này tích hợp sẵn Shiki (mặc định) và Prism, cho phép tự động phân tích cú pháp (syntax highlighting) cho hàng trăm ngôn ngữ lập trình ngay từ lúc build.

Tự động tạo ID cho Tiêu đề (Headings)#

Mọi thẻ ## Tiêu đề trong bài viết của bạn sẽ được tự động chuyển thành <h2 id="tieu-de">Tiêu đề</h2>. Điều này giúp bạn dễ dàng tạo các liên kết neo (anchor links) trỏ thẳng đến từng phần của bài viết.

3. Cách Tự Cấu Hình và Mở Rộng Sức Mạnh#

Điểm tuyệt vời nhất của @astrojs/markdown-remark là tính mở rộng thông qua hệ sinh thái plugin khổng lồ của Remark và Rehype. Bạn không cần cài đặt trực tiếp gói này vì Astro đã bọc sẵn cấu hình thông qua tệp astro.config.mjs.

Dưới đây là cách bạn có thể can thiệp vào pipeline xử lý để thêm các tính năng nâng cao:

Ví dụ 1: Thêm plugin tự động tạo mục lục (Table of Contents)#

Nếu bạn muốn bài viết tự động sinh ra mục lục từ các thẻ H2, H3, bạn có thể cài đặt plugin remark-toc:

bun add remark-toc

shell

Sau đó cấu hình trong astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: {
    // Tích hợp trực tiếp vào pipeline của @astrojs/markdown-remark
    remarkPlugins: [
      [remarkToc, { heading: 'Mục lục' }] // Tự động chèn TOC dưới tiêu đề "Mục lục"
    ],
  },
});

Ví dụ 2: Tự viết tính năng “Thời gian đọc bài” (Reading Time)#

Bạn cũng có thể tận dụng API của @astrojs/markdown-remark để can thiệp vào thuộc tính frontmatter của tệp khi đang build.

Hãy tạo một plugin nhỏ để tính số chữ và suy ra thời gian đọc:

astro.config.mjs

import { defineConfig } from 'astro/config';
import getReadingTime from 'reading-time'; // bun add reading-time
import { toString } from 'mdast-util-to-string';

// Plugin tùy chỉnh dựa trên kiến trúc remark của Astro
function remarkReadingTime() {
  return function (tree, { file }) {
    const textOnPage = toString(tree);
    const readingTime = getReadingTime(textOnPage);
    // Ghi đè hoặc thêm dữ liệu vào frontmatter
    file.data.astro.frontmatter.readingTime = readingTime.text;
  };
}

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkReadingTime],
  },
});

Bây giờ, trong trang Layout bài viết của Astro, bạn đã có thể truy cập thuộc tính này một cách mượt mà:

---
const { frontmatter } = Astro.props;
---
<p>Thời gian đọc: {frontmatter.readingTime}</p>
<h1>{frontmatter.title}</h1>

astro

Kết Luận#

@astrojs/markdown-remark không chỉ là một công cụ chuyển đổi định dạng đơn thuần, mà là một Content Pipeline cực kỳ mạnh mẽ. Nhờ vào kiến trúc mở dựa trên nền tảng Unified, nó mang lại cho nhà phát triển quyền kiểm soát tuyệt đối đối với cách nội dung văn bản được hiển thị, tối ưu hóa hiệu năng tải trang (zero-JS mặc định) và mở ra không gian sáng tạo vô hạn với các plugin.

Hy vọng bài viết này giúp bạn hiểu rõ hơn về “vị anh hùng thầm lặng” này trong hệ sinh thái Astro!

@astrojs/markdown-remark — Xử Lý Markdown Trong Astro