Bài viết này sẽ hướng dẫn bạn cách tùy biến và cấu hình trang tài liệu của Docusaurus theo nhu cầu sử dụng của bạn. Bạn sẽ được hướng dẫn cách sửa trên máy tính và chạy thử tại local trước khi xuất bản tài liệu. Bài viết cũng giới thiệu về cấu trúc file và thư mục của Docusaurus, cùng với các bước khai báo lại file cấu hình, thay đổi thông tin trang chủ và thêm tài liệu chi tiết. Hãy cùng khám phá nhé!
Cài đặt và tùy biến Docusaurus
Sau khi hoàn thành việc cài đặt Docusaurus, bước tiếp theo là tùy biến trang tài liệu theo nhu cầu sử dụng của chúng ta. Để làm điều này, chúng ta cần thành thạo việc sử dụng git và command line để có thể chỉnh sửa trên máy tính và chạy thử tại local trước khi đẩy lên github.com để xuất bản tài liệu. Mục tiêu chính của bài viết này là dành cho người mới bắt đầu, vì vậy chúng ta sẽ thao tác trên Github.com để cấu hình lại những thông tin quan trọng.
: Hướng dẫn tổ chức và bố cục trang chủ, sửa trang tài liệu chi tiết của Docusaurus
Bước tiếp theo sau khi cài đặt Docusaurus
Sau khi hoàn thành việc cài đặt Docusaurus, chúng ta cần thực hiện các bước sau:
- Khai báo lại file cấu hình docusaurus.config.js
- Thay logo và favicon
- Chuyển ngôn ngữ giao tiếp của tài liệu về tiếng Việt
- Khai báo lại thông tin đường dẫn tới repo trên github
- Thay đổi vùng thông tin chân trang
Khai báo lại file cấu hình docusaurus.config.js
Để khai báo lại file cấu hình docusaurus.config.js, bạn cần mở repo tài liệu của bạn trên github.com và click vào file docusaurus.config.js. Sau đó, bạn có thể chỉnh sửa thông tin chung như tiêu đề của tài liệu, phụ đề, và URL để truy cập vào tài liệu.
Thay logo và favicon
Để thay đổi logo và favicon của trang tài liệu, bạn cần upload file logo và favicon của bạn lên thư mục static/img sau đó khai báo lại trong file docusaurus.config.js. Bạn cần di chuyển xuống phía dưới để tìm đoạn thông tin về logo và thay đổi đường dẫn tới file logo và favicon của bạn.
Chuyển ngôn ngữ giao tiếp của tài liệu về tiếng Việt
Để chuyển ngôn ngữ giao tiếp của tài liệu về tiếng Việt, bạn cần tìm đoạn i18n trong file docusaurus.config.js và đổi giá trị defaultLocale và locales thành ‘vi’.
Khai báo lại thông tin đường dẫn tới repo trên github
Để khai báo lại thông tin đường dẫn tới repo trên github, bạn cần thay đổi giá trị của organizationName và projectName trong file docusaurus.config.js. OrganizationName là username hoặc tên tổ chức chứa repo, và projectName là tên repo trên github.
Thay đổi vùng thông tin chân trang
Để thay đổi vùng thông tin chân trang, bạn cần chỉnh sửa các liên kết trong vùng footer trong file docusaurus.config.js. Bạn có thể thay đổi tiêu đề và đường dẫn của các liên kết theo ý muốn.
Cấu trúc file và thư mục của Docusaurus
Docusaurus có một cấu trúc file và thư mục cụ thể để tổ chức tài liệu của bạn. Dưới đây là một số thư mục và file quan trọng trong cấu trúc của Docusaurus:
Thư mục blog
: Backlink là gì? Tìm hiểu từ A
Thư mục blog chứa các bài viết trong mục Blog của trang tài liệu. Mỗi bài viết được lưu trong một file có định dạng YYYY-MM-DD-ten-file.md. Bạn có thể sắp xếp các bài viết theo thứ tự thời gian bằng cách đặt tên file theo định dạng này.
Thư mục docs
Thư mục docs chứa các file tài liệu hướng dẫn. Bạn có thể tạo các file markdown trong thư mục này để viết nội dung chi tiết cho từng phần của tài liệu.
Thư mục src
Thư mục src chứa các file source để cấu hình và tùy chỉnh giao diện của trang tài liệu. Bạn có thể chỉnh sửa các file trong thư mục này để thay đổi giao diện và chức năng của trang.
Thư mục static
Thư mục static được sử dụng để lưu trữ các tệp tin ảnh và tài nguyên khác được sử dụng trong giao diện của trang tài liệu.
File docusaurus.config.js
File docusaurus.config.js chứa các thông tin cấu hình chung cho trang tài liệu, bao gồm tiêu đề, phụ đề, URL, logo, favicon và nhiều thông tin khác. Bạn có thể chỉnh sửa file này để tùy chỉnh trang tài liệu theo ý muốn.
File package.json
File package.json chứa thông tin kỹ thuật và các phụ thuộc cần thiết để máy chủ có thể đọc và biên dịch trang tài liệu. Bạn không cần chỉnh sửa file này trừ khi bạn muốn thêm các phụ thuộc mới cho trang tài liệu.
File README.md
File README.md là file index của repo trên Github. Nội dung của file này sẽ hiển thị thông tin mô tả cho repo khi bạn vào root của repo trên Github.
File sidebars.js
File sidebars.js chứa thông tin khai báo nâng cao cho menu đầu trang và menu trái của trang tài liệu. Bạn có thể chỉnh sửa file này để tùy chỉnh menu theo ý muốn.
Thêm trang tài liệu chi tiết
Để thêm các trang tài liệu chi tiết vào trang Docusaurus của bạn, bạn có thể thực hiện các bước sau:
Thêm và Sửa
: SEO là gì? Tại sao SEO rất quan trọng với mỗi website
Để thêm một trang tài liệu mới, bạn có thể tạo một file markdown trong thư mục docs. Sau đó, bạn có thể viết nội dung chi tiết cho trang tài liệu này bằng cách sử dụng cú pháp markdown. Bạn cũng có thể sửa đổi nội dung của các trang tài liệu hiện có bằng cách chỉnh sửa các file markdown tương ứng.
Xóa tài liệu
Để xóa một trang tài liệu, bạn chỉ cần xóa file markdown tương ứng trong thư mục docs. Sau khi xóa, trang tài liệu sẽ không còn hiển thị trên trang Docusaurus của bạn.
Đăng tin bài trong mục blog
Để đăng tin bài trong mục Blog của trang tài liệu Docusaurus, bạn cần thực hiện các bước sau:
Sửa file authors.yml
Trước tiên, bạn cần sửa file authors.yml để cung cấp thông tin về tác giả của bài viết. File này có cấu trúc tương tự như sau:
gobizme: name: Vinh Phạm title: Founder url: https://shopply.vn/ image_url: https://github.com/gobizme.png
Bạn cần điền thông tin của tác giả, bao gồm tên hiển thị, chức danh, URL đến website và URL ảnh đại diện của tác giả.
Tạo file tin bài trong thư mục blog
Sau khi đã sửa file authors.yml, bạn có thể tạo một file tin bài mới trong thư mục blog. File này cần có định dạng tên là YYYY-MM-DD-ten-file.md để đảm bảo các bài viết được sắp xếp theo thứ tự thời gian. Bạn có thể viết nội dung chi tiết của tin bài bằng cú pháp markdown trong file này.
Trong phần đầu của file tin bài, bạn cần cung cấp các thông tin như slug (đường dẫn URL), tiêu đề, tác giả, và các từ khóa (tags) liên quan. Bạn có thể sử dụng thông tin tác giả đã được khai báo trong file authors.yml hoặc khai báo tác giả mới nếu cần thiết.
Sau khi tạo và viết nội dung tin bài, bạn có thể commit và push lên Github để xuất bản tin bài trên trang Docusaurus của bạn.
Tóm lại, trong bài viết này chúng ta đã tìm hiểu về cách tùy biến trang tài liệu Docusaurus theo nhu cầu sử dụng của chúng ta. Chúng ta đã thao tác trên Github.com để cấu hình lại thông tin quan trọng như tiêu đề, phụ đề, logo, favicon và ngôn ngữ giao tiếp của tài liệu. Chúng ta cũng đã sửa nội dung trang chủ và thay đổi thông tin trong 3 box giới thiệu. Ngoài ra, chúng ta đã hướng dẫn thêm trang tài liệu chi tiết và đăng tin bài trong mục blog. Để mở rộng nhu cầu sử dụng, chúng ta cần tham khảo thông tin khác trên website chính thức của Docusaurus.
