Docusaurus và MkDocs

Trong bài viết này, tôi sẽ giải thích công cụ nào bạn có thể chọn cho tài liệu của mình. Cụ thể, tôi thảo luận về hai công cụ mà tôi khuyên dùng cho các biên tập viên kỹ thuật: Docusaurus và MkDocs Material

  Đọc 8 phút  

Mục tiêu là giúp bạn chọn một công cụ lập tài liệu sử dụng docs-as-code, Markdown và không mất nhiều thời gian để triển khai.

Giới thiệu

Mặc dù có nhiều công cụ tài liệu cho các nhà văn kỹ thuật, đôi khi ngay cả các nhà văn kỹ thuật giàu kinh nghiệm cũng tự hỏi: tôi nên sử dụng công cụ nào cho dự án của mình? Dự án của bạn có thể là Tài liệu tham khảo API hoặc tài liệu dành cho người dùng cuối, trợ giúp trực tuyến cho sản phẩm của bạn hoặc bất kỳ miền nào khác. Trong bài viết này, tôi tập trung vào các tài liệu hướng đến khách hàng, không phải tài liệu nội bộ mà bạn viết trong các hệ thống wiki như Confluence hoặc CMS như SharePoint Online. Tất nhiên, bạn có thể có xác thực hoặc bảo vệ bằng mật khẩu cho trang tài liệu hướng đến khách hàng của mình.

Được rồi, vì vậy, người quản lý hoặc nhiệm vụ kiểm tra của bạn yêu cầu bạn đưa ra giải pháp tài liệu tốt nhất cho sản phẩm/API/bạn đặt tên cho nó. Họ thậm chí có thể cung cấp cho bạn một số gợi ý như Word, SharePoint hoặc thậm chí một số công cụ thương mại chưa biết để xây dựng các trang web tài liệu. Câu hỏi đầu tiên tôi muốn hỏi là liệu họ đã sử dụng công cụ này trước đây và có hài lòng với nó hay không. Nếu cả hai câu trả lời đều là có, có lẽ không đáng để thuyết phục họ rằng công cụ của bạn sẽ làm tốt hơn. Tuy nhiên, bạn vẫn có thể tạo một trang web demo hoặc cho họ xem các dự án có sẵn được xây dựng bằng trình tạo trang web tĩnh Docusaurus hoặc MkDocs Material.

Tài liệu Docusaurus và MkDocs

Bạn đã nghe về Docusaurus và MkDocs Material chưa ? Đây là các trình tạo trang tĩnh (SSG) xây dựng một trang tài liệu tĩnh. Các SSG này sử dụng phương pháp docs-as-code , Markdown và git. Chúng được thiết kế dành riêng cho các nhà văn kỹ thuật hoặc nhà phát triển muốn xây dựng một trang tài liệu đẹp mắt một cách dễ dàng và nhanh chóng. Tôi đã viết một hướng dẫn toàn diện về cách bắt đầu làm việc với Docusaurus cách đây vài năm. Khi công cụ này được phát triển, một số thứ có thể đã thay đổi. Đó là lý do tại sao tôi sẽ thực hiện từng bước một lần nữa để triển khai một trang tài liệu Docusaurus.

MkDocs Material từ lâu đã nằm trong danh sách SSG tốt nhất của tôi cho các trang web tài liệu. Chủ đề Material của MkDocs được thiết kế cho những người viết tài liệu. Nó có nhiều tính năng, bạn nên tham khảo tài liệu của họ.

khủng long Docusaurus

Mục tiêu là xây dựng và triển khai trang web Docusaurus thử nghiệm. Sau đó, bạn có thể sao chép các bước để xây dựng trang web docs của riêng mình và triển khai nó lên GitHub Pages công khai.

Điều kiện tiên quyết

Bạn cần cài đặt những mục sau trên máy tính của mình.

Node.js

Bạn có thể kiểm tra xem nó đã được cài đặt chưa bằng cách nhập node -vvào terminal hoặc Command Prompt. Bạn cần v.18 trở lên.

Nếu bạn có phiên bản cũ hơn, hãy xóa nó bằng Windows Add or remove programs . Sau đó cài đặt phiên bản mới nhất từ đây .

Cài đặt gói Docusaurus

Sử dụng lệnh Node.js để cài đặt Docusaurus trên máy tính của bạn:

1. Chạy npm init docusaurus.

2. Nhập ykhi được yêu cầu và nhấn Enter.

   

3. Nhập tên trang web (dự án) của bạn khi được nhắc và nhấn Enter.

   

4. Chọn classicmẫu được đề xuất bằng cách nhấn Enter.

   

5. Chọn JavaScript bằng cách nhấn Enter.

   

6. Nhập cd test-docusaurus-docsđể chuyển đến thư mục chứa Docusaurus đã cài đặt.

7. Nhập npm startđể khởi động máy chủ tải lại nóng nhằm mở trang tài liệu trong trình duyệt của bạn trên máy chủ cục bộ.

   

Trang web của bạn mở trong trình duyệt với địa chỉ này: http://localhost:3000/

Triển khai Docusaurus lên GitHub Pages

Bây giờ bạn đã xây dựng trang web cục bộ, bạn có thể bắt đầu chỉnh sửa nội dung của trang web trong Markdown và tùy chỉnh chủ đề trang web: CSS, logo, tên, menu thanh bên, v.v. Tôi không có ý định trình bày tất cả các bước này như tôi đã mô tả ở đây . Thay vào đó, tôi sẽ cung cấp hướng dẫn triển khai trang web của bạn lên GitHub Pages để có thể truy cập trên internet.

1. Sử dụng VS Code để mở dự án Docusaurus của bạn: File > Open Folder… và chọn tên dự án mà bạn đã nhập khi cài đặt Docusaurus. Trong trường hợp của tôi, đó là test-docusaurus-docs.

2. Chọn tab Kiểm soát nguồn ở bảng điều khiển bên trái của VS Code.

   

3. Chọn Khởi tạo kho lưu trữ .

4. Chọn Cam kết .

   

5. Nhập tin nhắn cam kết. Ví dụ: cam kết đầu tiên. Nhấn Enter.

6. Chọn Xuất bản nhánh .

7. Chọn Xuất bản lên kho lưu trữ công khai GitHub .

   

8. Chọn Mở trên GitHub để mở dự án trong phiên bản web của GitHub.

   

Để triển khai trang web của bạn trên GitHub Pages:

1. Trong VS Code, hãy vào tab Explorer và chọn docusaurus.config.jstệp lưu trữ cấu hình trang web Docusaurus của bạn. Trong trường hợp của tôi, đường dẫn là C:\Users\ivanc\test-docusaurus-docs\docusaurus.config.js.

2. Thay đổi giá trị cho các tham số sau:

   • organizationName- Trong trường hợp của tôi, đó là ivanchebantài khoản GitHub của tôi.

   • projectName- Trong trường hợp của tôi, đó là test-docusaurus-docstên dự án Docusaurus mà bạn đã chọn và xuất bản lên GitHub.

   • url- Trong trường hợp của tôi thì là https://ivancheban.github.io.

   • baseUrl- Trong trường hợp của tôi thì là /test-docusaurus-docs/.

     

3. Trong thư mục gốc của dự án Docusaurus, hãy tạo deploy.ymltệp theo đường dẫn này: .github/workflows/deploy.yml. Điều này có nghĩa là trước tiên bạn tạo thư .githubmục, sau đó workflowstạo thư mục bên trong thư mục đó và sau đó mới tạo deploy.ymltệp. Dán mã sau vào deploy.ymltệp.

Tiếp tục triển khai trang web của bạn lên GitHub Pages:

1. Cam kết và đẩy những thay đổi của bạn:

   • Ctrl + Shift + P.
   • Lựa chọn Git: Commit All.
   • Thêm tin nhắn xác nhận.
   • Ctrl + Shift + P.
   • Lựa chọn Git: Push.

2. Tạo một gh-pagesnhánh trong dự án Docusaurus của bạn. Mặc dù bạn cam kết và đẩy vào mainnhánh, gh-pagesnhánh sẽ được sử dụng để triển khai trang web của bạn trên GitHub Pages.

3. Vào mục Cài đặt trên trang GitHub của dự án bạn.

   

4. Chọn Trang và chọn gh-pagesnhánh. Lưu thay đổi.

   

5. Vào Cài đặt > Môi trường và xóa khỏi gh-pagesgiới hạn.

   

6. Thay đổi bất kỳ thứ gì trong tệp cục bộ của bạn, cam kết và đẩy các thay đổi. Cam kết với nhánh chính sẽ bắt đầu triển khai trang web. Đợi trong khi đường ống hoàn tất việc xây dựng và triển khai trang web của bạn. Kiểm tra trang web đã xây dựng. Trong trường hợp của tôi, đó là: https://ivancheban.github.io/test-docusaurus-docs/ .

Tài liệu MkDocs

Mục tiêu là xây dựng và triển khai trang web MkDocs Material thử nghiệm. Sau đó, bạn có thể sao chép các bước để xây dựng trang web docs của riêng mình và triển khai nó lên GitHub Pages công khai.

Điều kiện tiên quyết

Bạn cần có Python với pip cho MkDocs. Sau đó, bạn có thể cài đặt MkDocs và các gói MkDocs Material bằng pip.

1. Đảm bảo Python đã được cài đặt : Bạn có thể kiểm tra xem Python đã được cài đặt trên hệ thống của bạn chưa bằng cách mở dấu nhắc lệnh và nhập python --version. Nếu Python đã được cài đặt, bạn sẽ thấy nội dung tương tự như Python 3.11.3. Nếu bạn chưa cài đặt Python, hãy cài đặt từ trang web chính thức của họ .

2. Đảm bảo pip đã được cài đặt : Bạn có thể kiểm tra xem pip đã được cài đặt chưa bằng cách nhập pip --versionvào dấu nhắc lệnh. Nếu pip đã được cài đặt, nó sẽ hiển thị phiên bản.

3. Cài đặt MkDocs : Nhập pip install mkdocsvào dấu nhắc lệnh. Đảm bảo MkDocs đã được cài đặt bằng cách nhập mkdocs --version.

4. Cài đặt MkDocs Material : Nhập pip install mkdocs-materialvào dấu nhắc lệnh. Để kiểm tra xem MkDocs Material đã được cài đặt chưa, hãy nhập mkdocs serve --help. Lệnh này sẽ liệt kê material là một tùy chọn trong --theme. Nếu material được liệt kê, điều đó có nghĩa là Material for MkDocs đã được cài đặt đúng.

   

Để biết thêm thông tin, hãy xem Cài đặt MkDocs và Cài đặt MkDocs Material .

Cài đặt trang web MkDocs

Bạn có thể tiếp tục tạo một trang MkDocs Material hoàn toàn mới bằng cách sử dụng các hướng dẫn này . Hoặc, bạn có thể fork kho lưu trữ của tôi với cấu hình đã sẵn sàng:

1. Tải xuống hoặc chia sẻ dự án đã nén từ đây: https://github.com/ivancheban/my-project .

2. Mở mkdocs.ymltệp để chỉnh sửa cấu hình trang web của bạn.

Để chạy trang web trên máy chủ cục bộ của bạn, hãy nhập: mkdocs serve. Thao tác này sẽ khởi động trang web trong trình duyệt của bạn bằng địa chỉ này: http://127.0.0.1:8000/my-project/ .

Triển khai MkDocs Material vào GitHub Pages

Bây giờ bạn đã kiểm tra xem trang MkDocs Material của mình có hoạt động cục bộ hay không, đã đến lúc triển khai nó trên GitHub dưới dạng trang công cộng.

1. Sử dụng các bước từ 1–8 khi triển khai trang web Docusaurus lên GitHub để cam kết và đẩy dự án MkDocs của bạn lên kho lưu trữ GitHub.

2. Tạo một gh-pagesnhánh trong kho lưu trữ của bạn.

3. Trong giao diện web của kho lưu trữ, hãy vào Cài đặt > Trang và chọn gh-pagesnhánh để triển khai trang web của bạn. Lưu các thay đổi.

4. Tại thư mục gốc của dự án MkDocs, hãy tạo một tệp quy trình làm việc GitHub Actions mới: .github/workflows/ci.yml, rồi sao chép và dán nội dung sau:

Cam kết và thúc đẩy những thay đổi của bạn.

Nhận xét

Trang này có hữu ích không?

Lần sửa đổi cuối cùng vào ngày 4 tháng 5 năm 2024: đã thay đổi kích thước hình ảnh (f3027b5)