Posted inDevelopment

Docusaurus: Xây dựng trang tài liệu chuẩn Docs-as-Code không còn là ‘ác mộng’

Development tutorial - IT technology blog
Development tutorial - IT technology blog

Tài liệu kỹ thuật: Từ “cực hình” đến quy trình tự động

Bạn đã bao giờ mất 3 tiếng đồng hồ chỉ để căn chỉnh bảng biểu trên Google Docs hay loay hoay copy-paste code từ VS Code sang Word chưa? Hồi mới vào nghề, mình từng ám ảnh mỗi khi sếp bảo cập nhật hướng dẫn API. Chỉ cần logic code thay đổi một chút, toàn bộ file tài liệu 50 trang lập tức trở nên lỗi thời và vô dụng.

Nếu bạn đang kẹt trong vòng lặp đó, Docs-as-Code chính là lối thoát. Hiểu đơn giản, chúng ta quản lý tài liệu y hệt cách quản lý mã nguồn: viết bằng Markdown, lưu trên Git, review qua Pull Request và tự động hóa việc triển khai. Trong hệ sinh thái này, Docusaurus hiện là lựa chọn hàng đầu nhờ khả năng tùy biến cao và hiệu suất ấn tượng.

Đây là bộ công cụ tạo trang web tĩnh (Static Site Generator) do Meta phát triển dựa trên React. Nó biến những file Markdown khô khan thành một trang web chuyên nghiệp, tích hợp sẵn chế độ Dark Mode và thanh tìm kiếm chỉ trong vài phút. Những dự án lớn như React, Tailwind CSS hay Algolia đều đang tin dùng công cụ này.

Tại sao bạn nên chọn Docusaurus thay vì README.md?

Việc để tất cả hướng dẫn vào một file README dài dằng dặc thường khiến người đọc nản lòng. Docusaurus giải quyết vấn đề này bằng những ưu điểm vượt trội:

  • Sức mạnh của MDX: Bạn không chỉ viết văn bản thuần túy. MDX cho phép nhúng trực tiếp các component React vào tài liệu. Bạn có thể tạo các nút bấm tương tác hoặc biểu đồ ngay giữa bài viết.
  • Cấu trúc phân tầng thông minh: Hệ thống hỗ trợ chia phiên bản (versioning), đa ngôn ngữ (i18n) và thanh sidebar đa cấp. Điều này cực kỳ quan trọng khi dự án của bạn phình to theo thời gian.
  • Tốc độ và SEO: Trang web được build ra có điểm Lighthouse thường đạt mức 90-100. Tốc độ load nhanh giúp trải nghiệm người dùng mượt mà và thân thiện với Google Bot.

Khởi tạo trang tài liệu đầu tiên trong 5 phút

Để bắt đầu, hãy đảm bảo máy bạn đã cài Node.js (phiên bản 18 trở lên). Hãy mở terminal và chạy lệnh khởi tạo:

npx create-docusaurus@latest my-docs classic

Lệnh này sẽ thiết lập một thư mục my-docs với giao diện mẫu tiêu chuẩn. Sau đó, bạn chỉ cần di chuyển vào thư mục và khởi động server:

cd my-docs
npm start

Truy cập http://localhost:3000, bạn sẽ thấy một trang tài liệu chuyên nghiệp hiện ra. Mọi thay đổi bạn thực hiện trong code sẽ được cập nhật tức thì (Hot Reload).

Giải mã cấu trúc thư mục

Docusaurus sắp xếp mọi thứ rất khoa học để bạn dễ dàng quản lý:

  • /docs/: “Trái tim” của dự án, nơi chứa toàn bộ file Markdown hướng dẫn kỹ thuật.
  • /blog/: Nơi đăng tải các bài viết cập nhật hoặc tin tức liên quan.
  • /src/: Dành cho những ai muốn can thiệp sâu vào giao diện bằng React và CSS.
  • docusaurus.config.js: File điều khiển trung tâm để thay đổi logo, menu và các plugin.

Viết nội dung và tối ưu Sidebar

Thử tạo file docs/cai-dat.md. Bạn sẽ thấy sức mạnh của phần Front Matter:

---
id: cai-dat
title: Hướng dẫn cài đặt
sidebar_label: Cài đặt nhanh
sidebar_position: 1
---

# Bắt đầu dự án

Để cài đặt thư viện, hãy chạy lệnh:

```bash
npm install my-lib
```

:::tip Lưu ý
Sử dụng Node.js bản LTS để tránh các lỗi vặt không đáng có.
:::

Thay vì phải sửa file cấu hình menu phức tạp, bạn chỉ cần thay đổi sidebar_position. Docusaurus sẽ tự động sắp xếp lại thứ tự bài viết trên thanh menu bên trái cho bạn.

Kinh nghiệm thực tế cho thấy bạn nên chia nhỏ tài liệu theo từng module. Đừng bao giờ dồn 2000 dòng vào một file duy nhất. Việc chia nhỏ giúp team review Pull Request nhanh hơn và người dùng cũng dễ tra cứu thông tin cụ thể hơn.

Tùy biến giao diện chuyên nghiệp

Mở file docusaurus.config.js để cá nhân hóa trang web. Đây là nơi bạn định nghĩa bản sắc cho dự án:

const config = {
  title: 'DevDocs Pro',
  tagline: 'Tài liệu kỹ thuật cho lập trình viên',
  url: 'https://docs.cua-ban.com',
  
  themeConfig: {
    navbar: {
      title: 'Trang chủ',
      items: [
        {type: 'doc', docId: 'intro', label: 'Tài liệu'},
        {to: '/blog', label: 'Blog', position: 'left'},
        {href: 'https://github.com/user/repo', label: 'GitHub', position: 'right'},
      ],
    },
  },
};

Một tính năng “đáng đồng tiền bát gạo” là Search. Thay vì tự viết code tìm kiếm, bạn có thể tích hợp Algolia DocSearch. Chỉ mất khoảng 10 phút cấu hình API key để có ngay thanh tìm kiếm thông minh như các trang docs lớn.

Tương tác hóa tài liệu với MDX

Đây là tính năng mình yêu thích nhất vì nó xóa nhòa ranh giới giữa văn bản và ứng dụng. Bạn có thể tạo ra các component trực quan để giải thích các khái niệm khó:

export const Badge = ({children, type}) => (
  <span className={`badge badge--${type}`}>{children}</span>
);

Trạng thái hiện tại: <Badge type="success">Hoạt động</Badge>

Khả năng này cực kỳ hữu ích khi bạn viết tài liệu cho Design System hoặc các thư viện UI, nơi người dùng cần xem demo thực tế ngay lập tức.

Triển khai (Deployment) thần tốc

Khi nội dung đã sẵn sàng, việc đưa nó lên Internet chỉ mất vài phút. Docusaurus tạo ra các file tĩnh nên bạn có thể host miễn phí trên GitHub Pages, Vercel hoặc Netlify.

Chạy lệnh build để đóng gói dự án:

npm run build

Kết quả sẽ nằm trong thư mục build/. Nếu sử dụng GitHub Actions, bạn có thể thiết lập quy trình CI/CD tự động. Cứ mỗi khi bạn push Markdown mới lên nhánh main, trang tài liệu sẽ tự động cập nhật sau khoảng 60-90 giây.

Lời kết

Trong một dự án thực tế với hơn 50.000 dòng code, mình nhận ra rằng: code giỏi đến đâu mà thiếu tài liệu thì người mới cũng sẽ “bơi” trong tuyệt vọng. Áp dụng Docusaurus giúp team mình giảm 40% thời gian onboarding nhân sự mới. Đừng coi việc viết tài liệu là một gánh nặng. Hãy coi đó là cách bạn xây dựng một sản phẩm hoàn chỉnh và chuyên nghiệp.

Share:
Tags: