Xin chào mọi người! Bạn đã từng gặp khó khăn khi viết tài liệu phần mềm? Bạn muốn có một cách nhanh chóng và dễ dàng để tạo ra các trang web tài liệu trực quan? Trong bài viết này, chúng ta sẽ tìm hiểu về Docusaurus – một dự án mã nguồn mở được xây dựng bởi Facebook. Docusaurus cho phép bạn viết tài liệu dưới dạng Markdown và tùy chỉnh một cách linh hoạt. Bạn có thể sử dụng Docusaurus để tạo trang tài liệu tĩnh hoặc xây dựng trang web cá nhân, sản phẩm, blog và nhiều hơn nữa. Hãy cùng khám phá Docusaurus và tận hưởng sự tiện lợi mà nó mang lại!
Docusaurus: Giới thiệu và cài đặt
1. Docusaurus là gì?
Docusaurus là một công cụ mã nguồn mở giúp viết tài liệu dưới dạng Markdown một cách dễ dàng và linh hoạt. Với Docusaurus, bạn có thể tạo ra các trang web tài liệu trực quan và tùy chỉnh chúng một cách nhanh chóng.
Docusaurus được phát triển bởi Facebook, đảm bảo tính ổn định và hiệu suất cao. Nếu bạn đã có kinh nghiệm với React, việc tùy chỉnh Docusaurus sẽ trở nên dễ dàng và thuận tiện hơn bao giờ hết. Tuy nhiên, nếu bạn không quen thuộc với React, không sao cả! Bạn chỉ cần tập trung vào việc tạo nội dung bằng Markdown.
Ngoài việc tạo tài liệu, bạn cũng có thể sử dụng Docusaurus để xây dựng trang web cá nhân, sản phẩm, blog, trang đích tiếp thị và nhiều hơn nữa. Tuy nhiên, trong bài viết này, chúng ta sẽ tập trung vào việc tạo tài liệu tĩnh với Docusaurus.
2. Các bước cài đặt
Để cài đặt Docusaurus, bạn chỉ cần thực hiện một câu lệnh đơn giản: `npx @docusaurus/init@latest init my-website classic`.
Trong câu lệnh trên, `npx` là một công cụ giúp chạy các gói npm mà không cần cài đặt chúng trước. `@docusaurus/init@latest` là tên gói và `init` là lệnh khởi tạo. `my-website` là tên dự án của bạn và `classic` là một loại template mà bạn muốn sử dụng.
Nếu bạn không chỉ định loại template trong câu lệnh, bạn sẽ được yêu cầu chọn một loại template trong quá trình cài đặt. Hiện tại, có ba loại template có sẵn là classic, bootstrap và facebook.
Sau khi câu lệnh chạy thành công, bạn sẽ nhận được kết quả như sau:
“`
Run project
Các bạn có thể thấy 2 lệnh tiếp theo cần để run project là truy cập vào thư mục dự án: cd my-website và sau đó run project bằng lệnh yarn start hoặc bạn cũng có thể chạy bằng lệnh npx docusaurus start. Sau khi chạy thành công bạn mở đường dẫn http://localhost:3000 và đây là kết quả
“`
Bây giờ, bạn đã cài đặt thành công Docusaurus và sẵn sàng để tạo tài liệu tuyệt vời cho dự án của mình!
Cấu trúc thư mục dự án
Các thành phần
: Keyword Search Volume — Chỉ số “lừa dối” nhất trong SEO
Khi bạn tạo một dự án với Docusaurus, bạn sẽ thấy một cấu trúc thư mục được tổ chức một cách rõ ràng và có các thành phần quan trọng sau:
– `/blog/`: Thư mục này chứa các file markdown cho blog của bạn. Nếu bạn không có kế hoạch xây dựng một blog, bạn có thể xóa thư mục này mà không gặp vấn đề gì. Tuy nhiên, nếu bạn quan tâm đến việc tạo blog, bạn có thể tìm hiểu thêm về cách cài đặt và sử dụng nó.
– `/docs/`: Đây là nơi chứa toàn bộ các file Markdown cho tài liệu của bạn. Bạn có thể tổ chức các file theo cách bạn muốn và tạo các trang tài liệu theo chủ đề hoặc loại.
– `/build/`: Thư mục này chứa mã nguồn của bạn sau khi đã được build. Bạn có thể triển khai trực tiếp thư mục này lên GitHub Pages hoặc Netlify.
– `/src/`: Thư mục này chứa các thành phần không phải là tài liệu của bạn, chẳng hạn như các trang hoặc các thành phần React khác mà bạn viết.
– `/static/`: Thư mục này chứa các tài nguyên tĩnh của bạn, như hình ảnh. Bạn có thể đặt các tệp tin tại đây và sử dụng chúng trong tài liệu của bạn.
– `/sidebar.js`: Tệp tin này được sử dụng để chỉ định thứ tự các trang tài liệu trên thanh bên của trang web. Bạn có thể tùy chỉnh thứ tự và cấu trúc của các trang tài liệu theo ý muốn.
Đây là một số thành phần quan trọng trong cấu trúc thư mục của dự án Docusaurus. Bạn có thể tìm hiểu thêm về các thành phần khác và cách sử dụng chúng trong các bài viết khác hoặc tìm hiểu thêm từ tài liệu chính thức của Docusaurus.
Các thành phần trong 1 file Markdown của bạn
Front Matter
File tài liệu Markdown của bạn có một số thành phần quan trọng được đặt ở đầu file, gọi là Front Matter. Front Matter giúp bạn chỉ định các thông tin quan trọng về trang tài liệu của bạn.
Ví dụ, dưới đây là một ví dụ về Front Matter:
“`
—
title: Hello
sidebar_label: “Xin chào”
sidebar_position: 1
slug: /my-custom-url
—
“`
: Meta Description là gì? Cách viết thẻ mô tả chuẩn SEO TOP 1
Trong ví dụ trên, các thuộc tính trong Front Matter bao gồm:
– `title`: Đây là tiêu đề của trang tài liệu và sẽ được hiển thị trên thanh tab của trình duyệt.
– `sidebar_label`: Đây là tên hiển thị của trang tài liệu trên thanh bên (sidebar). Nó có thể khác với tiêu đề chính của trang.
– `sidebar_position`: Đây là vị trí của trang tài liệu trong thanh bên (sidebar). Bạn có thể chỉ định một số nguyên để xác định vị trí của trang. Ví dụ: nếu bạn đặt giá trị là 1, trang sẽ được hiển thị ở vị trí đầu tiên trong thanh bên.
– `slug`: Đây là đường dẫn URL tùy chỉnh cho trang tài liệu của bạn. Bạn có thể đặt một URL mong muốn cho trang của mình.
Front Matter giúp bạn tùy chỉnh và quản lý các thuộc tính của trang tài liệu một cách linh hoạt và dễ dàng. Bằng cách sử dụng Front Matter, bạn có thể tạo ra các trang tài liệu đa dạng và phong phú cho dự án của mình.
Các bước deploy và chạy thử trên Netlify
Chạy thử trên Netlify
Để chạy thử dự án của bạn trên Netlify, bạn cần thực hiện các bước sau:
1. Đăng nhập vào Netlify và nhấp vào nút “New site from Git”.
2. Chọn nền tảng Git mà bạn sử dụng để quản lý mã nguồn của dự án (ví dụ: GitHub, GitLab, Bitbucket).
3. Cho phép Netlify truy cập vào repository của bạn bằng cách xác thực tài khoản của bạn.
4. Sau khi chọn repository, bạn sẽ thấy các tùy chọn cấu hình như branch sẽ được build, lệnh build và thư mục chứa mã nguồn sau khi build.
5. Bạn có thể tùy chỉnh các tùy chọn này để phù hợp với dự án của bạn. Ví dụ: bạn có thể thay đổi lệnh build, tên thư mục chứa mã nguồn sau khi build, miễn là bạn đã cấu hình đúng trong mã nguồn của dự án.
6. Nhấp vào nút “Deploy site” và Netlify sẽ bắt đầu quá trình build và triển khai dự án của bạn.
7. Sau khi quá trình triển khai thành công, bạn sẽ nhận được một đường dẫn URL cho trang web của bạn trên Netlify.
Bây giờ, bạn có thể truy cập vào đường dẫn URL được tạo ra và kiểm tra kết quả của dự án trên Netlify.
Ghi chú
Docusaurus là một công cụ mạnh mẽ để tạo tài liệu cho các dự án của bạn. Tôi đã được yêu cầu viết tài liệu hướng dẫn cho các chức năng, giải thích mã nguồn tích hợp và hướng dẫn cài đặt các thành phần liên quan. Sử dụng Excel để làm điều này có thể tốn nhiều công sức, vì bạn phải căn chỉnh hình ảnh, văn bản và đoạn mã nguồn hướng dẫn. Vì vậy, tôi đã chọn Docusaurus vì nó cho phép xây dựng nhanh chóng và có hiệu suất tốt. Bạn có thể tự trải nghiệm và khám phá thêm các tính năng khác của Docusaurus như multiple language, theme, plugin, presets và responsive. Docusaurus là một dự án mã nguồn mở, vì vậy bạn có thể đóng góp ý tưởng hoặc bản dịch tiếng Việt cho nó.Tóm tắt nội dung: Docusaurus là một dự án mã nguồn mở cho phép viết tài liệu dưới dạng Markdown và tạo các trang web tài liệu trực quan nhanh chóng. Nó rất linh hoạt và dễ tùy chỉnh, đặc biệt phù hợp cho những người có kinh nghiệm với React. Docusaurus cũng có thể được sử dụng để xây dựng trang web cá nhân, sản phẩm, blog và trang đích tiếp thị. Việc cài đặt và chạy Docusaurus cũng rất đơn giản. Cấu trúc thư mục dự án rõ ràng và các thành phần trong file Markdown cũng được giải thích chi tiết. Cuối cùng, Docusaurus cũng hỗ trợ việc deploy và chạy thử trên Netlify.
Kết luận: Docusaurus là một công cụ mạnh mẽ và tiện ích để tạo tài liệu cho các dự án phần mềm. Với khả năng tùy chỉnh cao và khả năng tạo trang web tài liệu trực quan nhanh chóng, Docusaurus là lựa chọn tuyệt vời cho việc viết tài liệu dễ dàng và hiệu quả. Hãy thử nghiệm và trải nghiệm Docusaurus để tạo ra các tài liệu chất lượng cho dự án của bạn.
