Cài đặt
Cài đặt Docusaurus bao gồm một tập hợp các gói npm.
mẹo Sử dụng Fast Track để hiểu Docusaurus trong 5 phút ⏱!
Sử dụng
docusaurus.new
để kiểm tra Docusaurus ngay lập tức trong trình duyệt của bạn!
Yêu cầu Node.js phiên bản 18.0 trở lên (có thể kiểm tra bằng cách chạy). Bạn có thể sử dụng nvm để quản lý nhiều phiên bản Node trên một máy duy nhất được cài đặt.node -v Khi cài đặt Node.js, bạn nên chọn tất cả các hộp kiểm liên quan đến phụ thuộc. Website dự án giàn giáo Cách dễ nhất để cài đặt Docusaurus là sử dụng công cụ dòng lệnh giúp bạn dựng một trang web Docusaurus khung xương. Bạn có thể chạy lệnh này ở bất kỳ đâu trong kho lưu trữ trống mới hoặc trong kho lưu trữ hiện có, nó sẽ tạo ra một thư mục mới chứa các tệp giàn giáo.
npx create-docusaurus@latest my-website classic
Chúng tôi khuyên bạn nên sử dụng mẫu này để bạn có thể bắt đầu nhanh chóng và nó chứa các tính năng có trong Docusaurus 1. Mẫu bao gồm tài liệu tiêu chuẩn, blog, trang tùy chỉnh và khung CSS (hỗ trợ chế độ tối). Bạn có thể thiết lập và chạy cực kỳ nhanh chóng với mẫu cổ điển và tùy chỉnh mọi thứ sau này khi bạn đã quen thuộc hơn với Docusaurus.classicclassic@docusaurus/preset-classic
Bạn cũng có thể sử dụng biến thể TypeScript của mẫu bằng cách chuyển cờ. Xem Hỗ trợ TypeScript để biết thêm thông tin.--typescript
npx create-docusaurus@latest my-website classic --typescript
Chỉ meta Nếu bạn đang thiết lập một trang web Docusaurus mới cho một dự án mã nguồn mở Meta, hãy chạy lệnh này bên trong một kho lưu trữ nội bộ, đi kèm với một số mặc định hữu ích dành riêng cho Meta:
scarf static-docs-bootstrap
Các lệnh cài đặt thay thế Chạy hoặc xem tài liệu API của nó để biết thêm thông tin về tất cả các cờ có sẵn.
npx create-docusaurus@latest --help
Cơ cấu dự án Giả sử bạn đã chọn mẫu cổ điển và đặt tên cho trang web của mình, bạn sẽ thấy các tệp sau được tạo trong một thư mục mới:my-websitemy-website/
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
Tóm tắt cấu trúc dự án /blog/ - Chứa các tệp Markdown blog. Bạn có thể xóa thư mục nếu bạn đã tắt plugin blog hoặc bạn có thể thay đổi tên của nó sau khi đặt tùy chọn. Thông tin chi tiết có thể được tìm thấy trong hướng dẫn blogpath /docs/ - Chứa các tệp Markdown cho tài liệu. Tùy chỉnh thứ tự của thanh bên tài liệu trong . Bạn có thể xóa thư mục nếu bạn đã tắt plugin tài liệu hoặc bạn có thể thay đổi tên của nó sau khi đặt tùy chọn. Bạn có thể tìm thêm chi tiết trong hướng dẫn tài liệusidebars.jspath /src/ - Các tệp không phải tài liệu như các trang hoặc các thành phần React tùy chỉnh. Bạn không cần phải đặt các tệp không phải tài liệu của mình ở đây, nhưng đặt chúng trong một thư mục tập trung giúp bạn dễ dàng chỉ định hơn trong trường hợp bạn cần thực hiện một số loại linting/xử lý /src/pages - Bất kỳ tệp JSX/TSX/MDX nào trong thư mục này sẽ được chuyển đổi thành trang web. Thông tin chi tiết có thể được tìm thấy trong hướng dẫn trang /static/ - Thư mục tĩnh. Bất kỳ nội dung nào bên trong đây sẽ được sao chép vào gốc của thư mục cuối cùngbuild /docusaurus.config.js - Tệp cấu hình chứa cấu hình trang web. Điều này tương đương với trong Docusaurus v1siteConfig.js /package.json - Trang web Docusaurus là một ứng dụng React. Bạn có thể cài đặt và sử dụng bất kỳ gói npm nào bạn thích trong đó /sidebars.js - Được sử dụng bởi tài liệu để chỉ định thứ tự của tài liệu trong thanh bên Monorepos Nếu bạn đang sử dụng Docusaurus để ghi lại một dự án hiện có, monorepo có thể là giải pháp cho bạn. Monorepos cho phép bạn chia sẻ sự phụ thuộc giữa các dự án tương tự. Ví dụ: trang web của bạn có thể sử dụng các gói địa phương của bạn để giới thiệu các tính năng mới nhất thay vì phụ thuộc vào phiên bản phát hành. Sau đó, những người đóng góp của bạn có thể cập nhật tài liệu khi họ triển khai các tính năng. Một ví dụ về cấu trúc thư mục monorepo dưới đây:
my-monorepo
├── package-a # Another package, your actual project
│ ├── src
│ └── package.json # Package A's dependencies
├── website # Docusaurus root
│ ├── docs
│ ├── src
│ └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies
Trong trường hợp này, bạn nên chạy trong thư mục.npx create-docusaurus./my-monorepo
Nếu bạn đang sử dụng một nhà cung cấp dịch vụ lưu trữ như Netlify hoặc Vercel, bạn sẽ cần phải thay đổi trang web thành nơi gốc Docusaurus của bạn. Trong trường hợp này, đó sẽ là . Đọc thêm về cách định cấu hình lệnh bỏ qua trong tài liệu triển khai.Base directory./website
Đọc thêm về monorepos trong tài liệu Yarn (Yarn không phải là cách duy nhất để thiết lập monorepo, nhưng nó là một giải pháp phổ biến), hoặc kiểm tra Docusaurus và Jest để biết một số ví dụ thực tế.
Chạy máy chủ phát triển Để xem trước các thay đổi của bạn khi bạn chỉnh sửa tệp, bạn có thể chạy một máy chủ phát triển cục bộ sẽ phục vụ trang web của bạn và phản ánh các thay đổi mới nhất.
npm Sợi PNPM cd my-website npm run start
Theo mặc định, một cửa sổ trình duyệt sẽ mở ở http://localhost:3000.
Chúc mừng! Bạn vừa tạo trang web Docusaurus đầu tiên của mình! Duyệt xung quanh trang web để xem những gì có sẵn.
Xây dựng Docusaurus là một trình tạo trang web tĩnh hiện đại, vì vậy chúng ta cần xây dựng trang web thành một thư mục nội dung tĩnh và đặt nó trên máy chủ web để có thể xem. Để xây dựng trang web:
npm
Sợi
PNPM
npm run build
và nội dung sẽ được tạo trong thư mục, có thể được sao chép sang bất kỳ dịch vụ lưu trữ tệp tĩnh nào như trang GitHub, Vercel hoặc Netlify. Hãy xem tài liệu về triển khai để biết thêm chi tiết./build
Cập nhật phiên bản Docusaurus của bạn Có nhiều cách để cập nhật phiên bản Docusaurus của bạn. Một cách đảm bảo là thay đổi thủ công số phiên bản thành phiên bản mong muốn. Lưu ý rằng tất cả các gói -namespaced phải sử dụng cùng một phiên bản.package.json@docusaurus/
package.json
{
"dependencies": {
"@docusaurus/core": "3.6.3",
"@docusaurus/preset-classic": "3.6.3",
// ...
}
}
Sau đó, trong thư mục chứa , chạy lệnh cài đặt của trình quản lý gói của bạn:package.json
npm
Sợi
PNPM
npm install
mẹo npm install có thể báo cáo một số lỗ hổng và đề nghị ch ạy để giải quyết chúng. Thông thường, các lỗ hổng được báo cáo này, chẳng hạn như lỗ hổng RegExp DOS, là vô hại và có thể bị bỏ qua một cách an toàn. Cũng đọc bài viết này, phản ánh suy nghĩ của chúng tôi: kiểm toán npm: Broken by Design.npm audit
Để kiểm tra xem cập nhật đã diễn ra thành công chưa, hãy chạy:
npx docusaurus --version
Bạn sẽ thấy phiên bản chính xác dưới dạng đầu ra.
Ngoài ra, nếu bạn đang sử dụng Yarn, bạn có thể thực hiện:
yarn add @docusaurus/core @docusaurus/preset-classic
mẹo Sử dụng các tính năng mới chưa được phát hành của Docusaurus với thẻ dist @canary npm
Vấn đề? Yêu cầu trợ giúp trên Stack Overflow, trên kho lưu trữ GitHub của chúng tôi, máy chủ Discord của chúng tôi hoặc X.