Docusaurus: trình tạo tài liệu dựa trên React
/docusaurus
Docusaurus là công cụ Meta xây dựng để các dự án mã nguồn mở của họ có một trang tài liệu mà không ai phải tự ráp một pipeline build tĩnh từ đầu. Nó làm tốt đúng một việc: biến một thư mục Markdown và MDX thành trang tài liệu có versioning, với i18n tích hợp sẵn chứ không gắn thêm sau. Đó là lựa chọn hợp lý cho đội chưa có pipeline tài liệu, kém hấp dẫn hơn cho đội đã có sẵn hệ thống static site riêng.
Docusaurus là gì?
Docusaurus là một trình tạo trang tĩnh do Meta xây dựng riêng cho tài liệu của các dự án mã nguồn mở. Nó lấy file Markdown, MDX cùng một ít React rồi biên dịch thành một trang tài liệu tự host, gồm trang chủ, phần docs, và blog tùy chọn. Kết quả là một site tĩnh có thể host ở bất kỳ đâu, không phải một sản phẩm SaaS được host sẵn.
Các tính năng cốt lõi có sẵn
- ✓Sinh trang từ Markdown và MDX — viết tài liệu bằng Markdown thuần, chèn component React ngay trong file MDX khi cần thứ gì đó tương tác.
- ✓Có sẵn phần blog đi kèm docs, không phải cài thêm riêng.
- ✓Bản địa hóa (i18n) qua CrowdIn nên một site đa ngôn ngữ ra đời mà không cần dựng riêng một pipeline dịch thuật.
- ✓CLI khởi tạo (`npm init docusaurus@latest`) dựng xong một site chạy được chỉ trong một lệnh.
- ✓Trang chủ, phần docs và các trang hỗ trợ có thể tùy biến bằng theme React thay vì một template cố định.
- ✓Có sân chơi thử trực tiếp tại docusaurus.new để dùng thử ngay trên trình duyệt mà không cần cài đặt gì.
Docusaurus phù hợp với những dự án nào
- •Các dự án mã nguồn mở cần một trang tài liệu công khai mà không phải tự bảo trì công cụ build riêng.
- •Tài liệu sản phẩm hoặc API cho công ty muốn docs có versioning gắn theo từng bản phát hành.
- •Một site kết hợp docs và blog — release notes nằm ngay cạnh tài liệu tham chiếu.
- •Dự án có người dùng không nói tiếng Anh, cần tài liệu đã dịch mà không cần một toolchain thứ hai.
Cài đặt Docusaurus
Chạy `npm init docusaurus@latest` trong một thư mục trống rồi làm theo các bước CLI hỏi — lệnh này dựng sẵn một site chạy được với thư mục docs mẫu, blog và trang chủ. Nếu chỉ muốn thử trước, docusaurus.new mở ngay một sân chơi trực tiếp trên trình duyệt, không cần cài đặt. README không nói rõ yêu cầu phiên bản Node, chỉ dẫn tới trang tài liệu cài đặt đầy đủ, nên kiểm tra trang đó trước khi chạy CLI khởi tạo trên một toolchain cũ.
Vì sao các đội chọn Docusaurus
- ✓CLI dựng xong một site chạy được chỉ trong một lệnh, không phải tự ráp cấu hình từ nhiều file.
- ✓Bản địa hóa được xử lý qua tích hợp CrowdIn thay vì phải tự dựng i18n từ đầu.
- ✓Docs và blog nằm chung một project, nên release notes không cần một CMS riêng.
- ✓Mã nguồn theo giấy phép MIT, nên không tốn chi phí license khi dùng cho tài liệu của một dự án thương mại.
- ✓Được chính Meta xây dựng và dùng cho các dự án mã nguồn mở của họ, nên các luồng thao tác cốt lõi đã được kiểm nghiệm ngoài phạm vi dự án cá nhân.
Điểm hạn chế của Docusaurus
- △Viết tài liệu bên trong một pipeline build dựa trên React — một đội muốn dùng trình tạo static site không phải JS (như Hugo, Jekyll) sẽ không được lợi gì khi chuyển sang.
- △Hướng dẫn trong README chỉ dừng ở bước khởi tạo; tạo trang, theme, và cấu hình blog đều bị đẩy ra trang tài liệu bên ngoài thay vì nằm trong repo.
- △Bản địa hóa chạy qua CrowdIn cụ thể — nếu một đội đã có bản dịch trên nền tảng khác, đó là một cuộc di chuyển dữ liệu, không phải cắm vào là chạy.
Các lựa chọn thay thế Docusaurus đáng cân nhắc
Câu hỏi thường gặp
Docusaurus miễn phí và mã nguồn mở theo giấy phép MIT, do chính Meta duy trì trên GitHub. Riêng nội dung tài liệu trong repo (các file `.md` trong thư mục `/docs`) lại theo giấy phép Creative Commons riêng.
Docusaurus hỗ trợ đa ngôn ngữ (i18n) sẵn có, dùng CrowdIn để quản lý bản dịch cho nội dung site. Đây là tính năng nằm sẵn trong lõi dự án chứ không phải một plugin phải cài thêm.
README của repo không nêu chi tiết lệnh versioning, nhưng hệ thống docs của Docusaurus có sẵn một tính năng versioning: mỗi lần phát hành, docs hiện tại được lưu thành bản có version riêng để vẫn xem được. Xem tài liệu cài đặt được liên kết từ repo để biết lệnh cụ thể.
Docusaurus có sẵn phần blog tùy chọn, đi kèm docs, trang chủ và các trang hỗ trợ khác — nên bài blog và tài liệu tham chiếu nằm chung một site thay vì cần một CMS riêng.
README của repo mô tả Docusaurus là công cụ để xây dựng, triển khai và bảo trì trang web dự án, với đầu ra là một site tĩnh — GitHub Pages là một đích deploy tiêu chuẩn cho loại build đó. Repo dẫn ra trang tài liệu cài đặt đầy đủ, không phải README, để lấy lệnh deploy cụ thể.
Viết docs và bài blog bằng Markdown thuần trong Docusaurus không cần biết React — site do CLI tạo ra đã chạy được ngay. React chỉ cần đến khi một trang cần component tùy chỉnh bên trong MDX, hoặc khi muốn tùy biến theme và layout của site, và cả hai đều là phần README mô tả là 'customizable' chứ không bắt buộc.
Vấn đề mà Docusaurus giải quyết
Người duy trì dự án mã nguồn mở muốn có một trang tài liệu thật sự, chứ không chỉ một README dài, thường phải tự ráp nó từ một trình tạo static site, một theme, một plugin tìm kiếm, và một quy trình dịch thuật riêng lẻ. Docusaurus đóng gói tất cả (docs, blog, i18n, và trang chủ) sau một lệnh khởi tạo duy nhất thay vì bốn quyết định tách rời.
Cách sử dụng
Docs, bài blog và các trang page chỉ là file Markdown/MDX đặt vào các thư mục `docs`, `blog` và `src/pages` tương ứng; Docusaurus tự biến cấu trúc thư mục đó thành navigation của site. Thêm component React ngay trong file MDX khi một trang cần thứ gì tương tác hơn là chữ. README chỉ dẫn ra trang tài liệu chính thức cho mọi thứ sau bước cài đặt ban đầu — tạo trang, styling/layout, và cấu hình blog đều có hướng dẫn riêng thay vì nằm trong README của repo.
Nên dùng — và nên bỏ qua khi nào
Một đội chưa có sẵn trang tài liệu, quen dùng công cụ Node và viết Markdown, sẽ tận dụng Docusaurus tốt nhất — CLI cho ra một bản chạy được trước cả buổi trưa. Nên bỏ qua nếu tài liệu dự án cần nằm trên một stack không phải JS, hoặc đội đã có sẵn một hệ thống Jekyll/Hugo chạy ổn mà không ai muốn di chuyển. Nó cũng không hợp với người chỉ cần render đẹp một file README duy nhất — việc đó GitHub đã làm miễn phí.
Repo liên quan
Muốn nghe thêm một ý kiến về docusaurus?
Hỏi một AI đọc được trang này — một cú bấm là có ngay nhận định về docusaurus.