Tại sao tài liệu quyết định sự thành bại của một dự án
Mã nguồn tuyệt vời cũng trở nên vô dụng nếu không ai biết cách chạy nó. Tôi đã thấy nhiều thư viện xuất sắc bị lãng quên trên GitHub chỉ vì hướng dẫn “Bắt đầu” (Getting Started) là một mớ văn bản khó hiểu. Viết logic chỉ là một nửa công việc. Nửa còn lại là giải thích logic đó để đồng nghiệp—hoặc chính bạn trong tương lai—không lãng phí hàng giờ gỡ lỗi các vấn đề thiết lập cơ bản. Theo kinh nghiệm của tôi, tài liệu chất lượng cao là thứ phân biệt giữa một dự án sở thích cuối tuần và một công cụ cấp độ chuyên nghiệp.
Docusaurus là giải pháp yêu thích của tôi cho việc này. Được xây dựng bởi Meta, trình tạo trang tĩnh này tận dụng React để tạo ra các trang web nhanh, có khả năng tìm kiếm và đẹp mắt. Bạn không cần phải là một chuyên gia frontend để sử dụng nó. Nó quản lý các phần phức tạp như định tuyến (routing) và quản lý phiên bản (versioning), giúp bạn tự do viết Markdown đơn giản. Hướng dẫn này sẽ giúp bạn khởi chạy một trang web trong vòng chưa đầy năm phút và tự động hóa toàn bộ quy trình triển khai (deployment pipeline).
Bắt đầu nhanh (Thiết lập trong 5 phút)
Trước tiên, hãy đảm bảo máy tính của bạn đã cài đặt Node.js (phiên bản 18.0 trở lên). Bạn có thể kiểm tra phiên bản hiện tại bằng cách nhập node -v vào terminal.
1. Khởi tạo dự án
Chạy lệnh sau để tạo một trang web mới bằng mẫu “classic” tiêu chuẩn. Nó bao gồm một trang chủ, một blog và công cụ quản lý tài liệu:
npx create-docusaurus@latest my-docs classicLệnh này sẽ tạo một thư mục tên là my-docs. Sau khi trình cài đặt hoàn tất, hãy di chuyển vào thư mục đó:
cd my-docs2. Khởi chạy máy chủ phát triển
Khởi động bản xem trước cục bộ để xem các thay đổi của bạn trong thời gian thực:
npm startTrình duyệt của bạn sẽ tự động mở http://localhost:3000. Giờ đây bạn đã có một trang web đầy đủ chức năng với chế độ tối (dark mode), thanh tìm kiếm mẫu và thiết kế phản hồi (responsive) ngay lập tức.
Cấu trúc cốt lõi: Nơi đặt nội dung của bạn
Docusaurus giữ cho mọi thứ ngăn nắp bằng cách chia trang web thành các khu vực riêng biệt. Hiểu rõ bố cục này sẽ giúp bạn không phải tốn công tìm kiếm tệp tin sau này.
/docs: Trái tim của trang web. Mọi tệp Markdown ở đây sẽ tự động trở thành một trang tài liệu./blog: Hoàn hảo cho nhật ký thay đổi (changelogs) hoặc cập nhật dự án.docusaurus.config.js: Trung tâm điều khiển. Sử dụng tệp này để cập nhật tiêu đề trang, liên kết mạng xã hội và siêu dữ liệu SEO.sidebars.js: Tệp này quyết định thứ tự các trang của bạn. Nếu bạn muốn một luồng cụ thể cho bài hướng dẫn, bạn sẽ định nghĩa nó tại đây.
Nâng cao Markdown với MDX
Docusaurus sử dụng MDX, cho phép bạn nhúng trực tiếp các thành phần React vào tệp Markdown. Điều này cực kỳ hữu ích để làm nổi bật các thông tin quan trọng. Thay vì văn bản thuần túy, hãy sử dụng Admonitions để thu hút sự chú ý của người đọc:
:::tip Mẹo nhỏ
Sử dụng tên tệp có tính mô tả như 'authentication-setup.md' thay vì 'setup.md' để cải thiện SEO cho trang web của bạn.
:::Kiểm soát thanh bên (Sidebar)
Mặc dù Docusaurus có thể tự động tạo thanh bên, nhưng việc cấu hình thủ công sẽ mang lại trải nghiệm người dùng tốt hơn. Mở sidebars.js để tạo một cấu trúc phân cấp logic cho độc giả của bạn:
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: 'Khái niệm cốt lõi',
items: ['api-basics', 'authentication'],
},
],
};Tự động hóa mọi thứ với CI/CD
Việc tải tệp lên máy chủ một cách thủ công rất dễ dẫn đến sai sót. Bằng cách sử dụng GitHub Actions, tài liệu của bạn sẽ được cập nhật ngay khi bạn đẩy mã nguồn lên nhánh main.
1. Cấu hình URL chính thức
Bạn phải cho Docusaurus biết nó sẽ nằm ở đâu trên internet. Mở docusaurus.config.js và cập nhật các dòng sau với thông tin GitHub của bạn:
const config = {
title: 'Tài liệu dự án',
url: 'https://<your-username>.github.io',
baseUrl: '/my-docs/',
organizationName: '<your-username>',
projectName: 'my-docs',
trailingSlash: false,
// ...
};2. Xây dựng GitHub Action
Tạo một tệp tại .github/workflows/deploy.yml. Script này sẽ tự động hóa quá trình xây dựng mỗi khi bạn đẩy một thay đổi. nó xử lý việc cài đặt phụ thuộc và đẩy mã HTML cuối cùng lên nhánh gh-pages.
name: Triển khai lên GitHub Pages
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- name: Cài đặt & Xây dựng
run: |
npm install
npm run build
- name: Triển khai
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./buildMẹo chuyên nghiệp để có trải nghiệm người dùng tốt hơn
Sau khi xây dựng hàng chục trang tài liệu, tôi nhận thấy rằng những chi tiết nhỏ có tác động đáng kể đến mức độ hài lòng của người dùng khi sử dụng công cụ của bạn.
Thêm tìm kiếm tức thì
Đừng bắt người dùng phải lục lọi để tìm câu trả lời. Docusaurus tích hợp mượt mà với Algolia DocSearch. Khi trang web của bạn đã hoạt động, hãy đăng ký gói miễn phí của họ. Nó cung cấp một giao diện tìm kiếm cực nhanh, lập chỉ mục nội dung và trả về kết quả trong chưa đầy 100ms.
Quản lý phiên bản cho tài liệu
Nếu bạn phát hành một bản cập nhật lớn (như chuyển từ v1 sang v2), tài liệu cũ của bạn không nên biến mất. Hãy sử dụng công cụ quản lý phiên bản của Docusaurus. Nó thêm một menu thả xuống trên thanh điều hướng, cho phép người dùng chọn tài liệu phù hợp với phiên bản phần mềm họ đang thực sự sử dụng.
Giữ cho mọi thứ đơn giản
Tránh các đoạn văn dài dòng, lan man. Sử dụng các khối mã (code blocks) cho mọi câu lệnh, ngay cả những lệnh đơn giản như npm install. Đừng bao giờ giả định rằng người dùng đã biết các bước tiên quyết. Bằng cách viết tài liệu chi tiết từ những bước cơ bản nhất, bạn sẽ giảm bớt số lượng yêu cầu hỗ trợ và các vấn đề (issues) trên GitHub mà bạn phải trả lời sau này.
