Series Docusaurus – Quản lý tài liệu cho dự án một cách dễ dàng nhất – Phần 1

0

Hiện nay khi làm một dự án, điều mà các coder chúng ta thường hay quên mất hoặc bỏ qua khi hoàn thành một tính năng nào đó, đó chính là việc viết Unit Test và viết Documents cho tính năng đó. Việc viết tài liệu có thể dễ dàng với một số bạn, nhưng việc quản lý và lưu trữ tài liệu đồng bộ với từng dự án thì có thể các bạn sẽ gặp một số rắc rối. Trong series này mình sẽ giúp các bạn giải quyết việc viết documents hiệu quả cho project của bạn bằng công cụ có tên Docusaurus

1.Giới thiệu về Docusaurus

1. Docusaurus là gì?

Docusaurus đơn giản là một công cụ được thiết kế để giúp chúng ta quản lý cũng như tạo ra các Document mà không cần phải lo lắng về cơ sở hạ tầng quản lý cũng như chi tiết thiết kế.

Tất cả người dùng chỉ cần cung cấp các Document được viết bằng MarkDown, tuỳ chỉnh giao diện (Viết bằng React) theo ý thích của mình và sửa đổi cấu hình là xong, Docusaurus sẽ cung cấp cho chúng ta những file Document mặc định để dễ dàng viết hơn và xử lý những phần còn lại, rất đơn giản phải không

2. Tại sao chúng ta nên viết document cho dự án bằng Docusaurus ?

  • Giúp chúng ta tập trung vào việc viết tài liệu tốt hơn thay vì lo lắng về cơ sở hạ tầng của một trang web.
  • Giúp chúng ta tạo ra một Blog của riêng mình một cách dễ dàng và nhanh chóng.
  • Dễ dàng đẩy các bản cập nhật, các tính năng mới hay là sửa lỗi cho tất cả mọi người cùng một lúc.
  • Thêm nữa nó còn hỗ trợ tìm kiếm thông qua Algolia hay hỗ trợ dịch thuật qua Crowdin

3. Docusaurus ra đợi như thế nào ?

Vào quý 2 năm 2017, Docusaurus được phát triển bởi Facebook như là một “open source documentation”

Hiện đang có khoảng 7.6k stars trên Github, nó đang được coi là dự án phổ biến nhất hiện nay

Vậy chúng ta hãy cùng bắt đầu với Docusaurus. Trong bài viết này mình xin phép được chia sẻ hướng dẫn cài đặt cũng như chạy thử một website mẫu. Hãy cùng bắt tay vào làm nào J

2. Cài đặt Docusaurus

Docusaurus được Facebook phát triển nên nó được thiết kế ngay từ những bước đầu sao cho dễ dàng cài đặt và sử dụng nhất giúp trang web của bạn hoạt động một cách nhanh chóng. Để sử dụng được Docusaurus thì bạn cần cài thêm Node.js

Để cài đặt Node các bạn hãy vào đường link này nhé https://nodejs.org/en/download/

Docusaurus yêu cầu Node.js bản từ 8.0 trở lên. Sau khi chạy xong thì bạn có thể vào Terminal (Ubuntu/Linux) hoặc Powershell ( Windows ) chạy lệnh sau

npx docusaurus-init

Câu lệnh trên sẽ tự động tìm nạp gói docusaurus-init và thực thi nó, từ đó tạo ra các tệp dự án. Nếu các bạn muốn tìm hiểu thêm về npx thì hãy bấm vào đây (https://www.npmjs.com/package/npx).
Sau khi tải xong thư mục của bạn sẽ tự động có cấu trúc như sau

Tiếp theo chúng ta hãy cùng chạy thử một Website mẫu nhé. Để chạy thử, chúng ta hãy vào thư mục website và sử dụng script npm start để chạy

cd website
npm start

Lúc này Docusaurus sẽ chạy dự án tại port 3000 và mở  http://localhost:3000 trên trình duyệt mặc định.

Docusaurus hỗ trợ tải lại trực tiếp trang khi có sự thay đổi trên Documents hay Blog. Nhưng các bạn hãy lưu ý rằng những tệp cấu hình (vd: siteConfig.js) thì yêu cầu phải khởi động lại dự án mới có hiệu lực.

Chúng ta hãy cùng hiểu rõ hơn về cấu trúc của dự án

  • /docs
    • Là nơi chứa các tài liệu của chúng ta, các tài liệu được lưu dưới định dạng .md (vd: /docs/example.md)
  • /website/siteConfig.js
    • Là nơi để cấu hình dự án của chúng ta.
  • /website/pages/en/index.js
    • Là nơi chứa trang chủ.
  • /website/sidebars.json
    • Nơi chứa silde bar của dự án
  • /website/static
    • Nơi chứa assets file
  • /website/core/Footer.js
    • Là nơi chứa Footer của trang
  • /website/blog
    • Là nơi chứa những bài viết blog

Tóm váy lại Docusaurus là một trình tạo Document khá đẹp và dễ dàng đúng không các bạn :v. Để có thể nắm rõ hơn về cấu trúc của Document cũng như cách tổ chức Document, các bạn hãy đón xem series 2 về Cấu trúc Document và kết hợp Docusaurus với github pages các bạn nhé. Chúc các bạn thành công

Tác giả : Nguyễn Hữu Hòa

Leave A Reply

Your email address will not be published.