Giới thiệu

Giới thiệu ⚡️ Docusaurus sẽ giúp bạn gửi một trang web tài liệu đẹp mắt ngay lập tức.

💸 Xây dựng một ngăn xếp công nghệ tùy chỉnh rất tốn kém. Thay vào đó, hãy tập trung vào nội dung của bạn và chỉ viết các tệp Markdown.

💥 Sẵn sàng cho nhiều hơn? Sử dụng các tính năng nâng cao như tạo phiên bản, i18n, tìm kiếm và tùy chỉnh chủ đề.

💅 Kiểm tra các trang web Docusaurus tốt nhất để lấy cảm hứng.

🧐 Docusaurus là một trình tạo địa điểm tĩnh. Nó xây dựng một ứng dụng một trang với điều hướng phía máy khách nhanh chóng, tận dụng toàn bộ sức mạnh của React để làm cho trang web của bạn trở nên tương tác. Nó cung cấp các tính năng tài liệu có sẵn nhưng có thể được sử dụng để tạo bất kỳ loại trang web nào (trang web cá nhân, sản phẩm, blog, trang đích tiếp thị, v.v.).

Theo dõi ⏱️ nhanh Hiểu Docusaurus trong 5 phút bằng cách chơi!

Tạo một trang web Docusaurus mới và làm theo hướng dẫn nhúng rất ngắn.

Cài đặt Node.js và tạo một trang web Docusaurus mới:

npx create-docusaurus@latest my-website classic

Bắt đầu trang web:

cd my-website npx docusaurus start

Mở http://localhost:3000 và làm theo hướng dẫn.

mẹo Sử dụng docusaurus.new để kiểm tra Docusaurus ngay lập tức trong trình duyệt của bạn!

Hoặc đọc hướng dẫn 5 phút trực tuyến.

Docusaurus: Tài liệu dễ dàng Trong bài thuyết trình này tại Sự kiện Cộng đồng Algolia, nhóm Meta Open Source đã chia sẻ một hướng dẫn ngắn gọn về Docusaurus. Họ đã đề cập đến cách bắt đầu với dự án, kích hoạt plugin và thiết lập các chức năng như tài liệu và viết blog.

Di chuyển từ phiên bản 1 Docusaurus v2+ đã được viết lại hoàn toàn từ Docusaurus v1, tận dụng một chuỗi công cụ được hiện đại hóa hoàn toàn. Sau khi bản phát hành chính thức của v2, chúng tôi thực sự khuyến khích bạn sử dụng Docusaurus v2+ thay vì Docusaurus v1, vì Docusaurus v1 đã không được dùng nữa.

Rất nhiều người dùng đã sử dụng Docusaurus v2+ (xu hướng).

Sử dụng Docusaurus v2+ nếu:

✅ Bạn muốn có một trang web tài liệu Jamstack hiện đại ✅ Bạn muốn một ứng dụng một trang (SPA) với định tuyến phía máy khách ✅ Bạn muốn có toàn bộ sức mạnh của React và MDX ✅ Bạn không cần hỗ trợ cho IE11 Sử dụng Docusaurus v1 nếu:

❌ Bạn không muốn một ứng dụng một trang (SPA) ❌ Bạn cần hỗ trợ cho IE11 (... Bạn có phải không? IE đã hết hạn sử dụng và không còn được hỗ trợ chính thức) Đối với người dùng v1 hiện tại đang muốn nâng cấp lên v2+, bạn có thể làm theo hướng dẫn di chuyển của chúng tôi.

Tính năng Docusaurus được xây dựng với sự chú ý cao độ đến trải nghiệm của nhà phát triển và cộng tác viên.

⚛️ Được xây dựng với 💚 và Phản ứng: Mở rộng và tùy chỉnh với React Kiểm soát hoàn toàn trải nghiệm duyệt web của bạn bằng cách cung cấp các thành phần React của riêng bạn 🔌 Có thể cắm: Khởi động trang web của bạn bằng một mẫu cơ bản, sau đó sử dụng các tính năng và plugin nâng cao Mã nguồn mở plugin của bạn để chia sẻ với cộng đồng ✂️ Kinh nghiệm nhà phát triển: Bắt đầu viết tài liệu của bạn ngay bây giờ Điểm vào cấu hình phổ quát để làm cho nó dễ bảo trì hơn bởi những người đóng góp Tải lại nóng với bản dựng gia tăng nhanh như chớp trên các thay đổi Mã dựa trên tuyến đường và phân tách dữ liệu Xuất bản lên GitHub Pages, Netlify, Vercel và các dịch vụ triển khai khác một cách dễ dàng Mục tiêu chung của chúng tôi là giúp người dùng nhanh chóng tìm thấy những gì họ cần và hiểu rõ hơn về sản phẩm của bạn. Chúng tôi chia sẻ các phương pháp hay nhất để giúp bạn xây dựng trang web tài liệu của mình đúng và tốt.

🎯 Thân thiện với SEO: Các tệp HTML được tạo tĩnh cho mọi đường dẫn có thể. SEO dành riêng cho trang để giúp người dùng truy cập vào các tài liệu chính thức của bạn liên quan trực tiếp đến các vấn đề của họ. 📝 Được cung cấp bởi MDX: Viết các thành phần tương tác thông qua JSX và React được nhúng trong Markdown. Chia sẻ mã của bạn trong các trình chỉnh sửa trực tiếp để khiến người dùng yêu thích sản phẩm của bạn ngay tại chỗ. 🔍 Tìm kiếm: Toàn bộ trang web của bạn có thể tìm kiếm được. 💾 Phiên bản tài liệu: Giúp bạn đồng bộ hóa tài liệu với các bản phát hành dự án. 🌍 Quốc tế hóa (i18n): Dịch trang web của bạn ở nhiều ngôn ngữ. Docusaurus v2+ được sinh ra để tất cả người dùng của bạn có thể truy cập một cách nhân ái và nhanh như chớp.

⚡️ Nhanh như chớp. Docusaurus v2+ tuân theo Mẫu PRPL đảm bảo nội dung của bạn tải nhanh chóng. 🦖 Có thể truy cập. Chú ý đến khả năng truy cập, làm cho trang web của bạn có thể truy cập bình đẳng với tất cả người dùng. Nguyên tắc thiết kế Ít để học. Docusaurus nên dễ học và sử dụng vì API khá nhỏ. Hầu hết mọi thứ vẫn có thể đạt được bởi người dùng, ngay cả khi họ mất nhiều mã hơn và nhiều thời gian hơn để viết. Không có trừu tượng tốt hơn là có trừu tượng sai và chúng tôi không muốn người dùng phải hack các trừu tượng sai. Nói chuyện bắt buộc—Diện tích bề mặt API tối thiểu. Trực quan. Người dùng sẽ không cảm thấy choáng ngợp khi nhìn vào thư mục dự án của một dự án Docusaurus hoặc thêm các tính năng mới. Nó phải trông trực quan và dễ xây dựng, sử dụng các phương pháp tiếp cận mà họ quen thuộc. Kiến trúc phân lớp. Sự tách biệt của các mối quan tâm giữa mỗi lớp ngăn xếp của chúng ta (nội dung/chủ đề/kiểu dáng) phải rõ ràng — trừu tượng hóa và mô-đun. Mặc định hợp lý. Các cấu hình và tối ưu hóa hiệu suất phổ biến và phổ biến sẽ được thực hiện cho người dùng nhưng họ được cung cấp tùy chọn ghi đè chúng. Không có khóa nhà cung cấp. Người dùng không bắt buộc phải sử dụng các plugin hoặc CSS mặc định, mặc dù họ rất được khuyến khích. Không thể hoán đổi một số cơ sở hạ tầng cốt lõi như React Loadable và React Router vì chúng tôi thực hiện tối ưu hóa hiệu suất mặc định trên chúng, nhưng không phải những cơ sở hạ tầng cấp cao hơn. Việc lựa chọn các công cụ Markdown, khung CSS, phương pháp CSS và các kiến trúc khác sẽ hoàn toàn tùy thuộc vào người dùng. Chúng tôi tin rằng, với tư cách là nhà phát triển, biết cách thức hoạt động của thư viện sẽ giúp chúng tôi sử dụng nó tốt hơn. Do đó, chúng tôi đang nỗ lực giải thích kiến trúc và các thành phần khác nhau của Docusaurus với hy vọng rằng người dùng đọc nó sẽ hiểu sâu hơn về công cụ này và thậm chí còn thành thạo hơn trong việc sử dụng nó.

So sánh với các công cụ khác Trên tất cả các trình tạo trang web tĩnh, Docusaurus tập trung vào các trang web tài liệu và có nhiều tính năng vượt trội.

Chúng tôi cũng đã nghiên cứu các trình tạo trang web tĩnh chính khác và muốn chia sẻ thông tin chi tiết của chúng tôi về việc so sánh, hy vọng sẽ giúp bạn điều hướng qua các lựa chọn lăng trụ ngoài kia.

Gatsby Gatsby được tích hợp rất nhiều tính năng, có một hệ sinh thái plugin phong phú và có khả năng làm mọi thứ mà Docusaurus làm. Đương nhiên, điều đó phải trả giá bằng đường cong học tập cao hơn. Gatsby làm tốt nhiều việc và phù hợp để xây dựng nhiều loại trang web. Mặt khác, Docusaurus cố gắng làm một điều cực kỳ tốt - trở thành công cụ tốt nhất để viết và xuất bản nội dung.

GraphQL cũng là cốt lõi của Gatsby, mặc dù bạn không nhất thiết phải cần GraphQL để xây dựng một trang web Gatsby. Trong hầu hết các trường hợp khi xây dựng các trang web tĩnh, bạn sẽ không cần sự linh hoạt mà GraphQL cung cấp.

Nhiều khía cạnh của Docusaurus v2+ được lấy cảm hứng từ những điều tốt nhất về Gatsby và đó là một sự thay thế tuyệt vời.

Docz là một chủ đề Gatsby để xây dựng các trang web tài liệu. Nó hiện ít nổi bật hơn Docusaurus.

Next.js Next.js là một framework React lai rất phổ biến khác. Nó có thể giúp bạn xây dựng một trang web tài liệu tốt, nhưng nó không có ý kiến đối với trường hợp sử dụng tài liệu và nó sẽ đòi hỏi nhiều công việc hơn để thực hiện những gì Docusaurus cung cấp ngay lập tức.

Nextra là một trình tạo trang web tĩnh cố chấp được xây dựng trên Next.js. Nó hiện ít nổi bật hơn Docusaurus.

Báo chí VitePress VitePress có nhiều điểm tương đồng với Docusaurus - cả hai đều tập trung nhiều vào các trang web tập trung vào nội dung và cung cấp các tính năng tài liệu phù hợp. Tuy nhiên, VitePress được cung cấp bởi Vue, trong khi Docusaurus được cung cấp bởi React. Nếu bạn muốn một giải pháp dựa trên Vue, VitePress sẽ là một lựa chọn phù hợp.

MkDocs MkDocs là một trình tạo trang web tĩnh Python phổ biến với các đề xuất giá trị tương tự như Docusaurus.

Đây là một lựa chọn tốt nếu bạn không cần một ứng dụng một trang và không có kế hoạch tận dụng React.

Material for MkDocs là một chủ đề đẹp.

Tài liệu Docsify giúp bạn dễ dàng tạo một trang web tài liệu, nhưng không phải là một trình tạo trang web tĩnh và không thân thiện với SEO.

Sách GitBook GitBook có thiết kế rất sạch sẽ và đã được sử dụng bởi nhiều dự án mã nguồn mở. Với trọng tâm chuyển sang một sản phẩm thương mại hơn là một công cụ mã nguồn mở, nhiều yêu cầu của nó không còn phù hợp với nhu cầu của các trang web tài liệu của các dự án nguồn mở. Kết quả là, nhiều người đã chuyển sang các sản phẩm khác. Bạn có thể đọc về việc Redux chuyển sang Docusaurus tại đây.

Hiện tại, GitBook chỉ miễn phí cho các nhóm mã nguồn mở và phi lợi nhuận. Docusaurus miễn phí cho tất cả mọi người.

Jekyll Jekyll là một trong những trình tạo trang web tĩnh trưởng thành nhất xung quanh và là một công cụ tuyệt vời để sử dụng - trên thực tế, trước Docusaurus, hầu hết các trang web Mã nguồn mở của Facebook đều được xây dựng trên Jekyll! Nó cực kỳ đơn giản để bắt đầu. Chúng tôi muốn mang lại trải nghiệm tương tự cho nhà phát triển như việc xây dựng một trang web tĩnh với Jekyll.

So với HTML được tạo tĩnh và tính tương tác được thêm vào bằng cách sử dụng thẻ, các trang web Docusaurus là ứng dụng React. Sử dụng công cụ hệ sinh thái JavaScript hiện đại, chúng tôi hy vọng sẽ thiết lập các tiêu chuẩn mới về hiệu suất của các trang web tài liệu, quy trình xây dựng nội dung và tối ưu hóa cũng như dễ thiết lập.

Cập nhật thông tin GitHub X Bài viết Bất hòa Thiếu cái gì? Nếu bạn tìm thấy vấn đề với tài liệu hoặc có đề xuất về cách cải thiện tài liệu hoặc dự án nói chung, vui lòng gửi vấn đề cho chúng tôi hoặc gửi tweet đề cập đến tài khoản @docusaurus X.

Đối với các yêu cầu tính năng mới, bạn có thể tạo một bài đăng trên bảng yêu cầu tính năng của chúng tôi (Canny), đây là một công cụ tiện dụng để lập bản đồ đường bộ và cho phép sắp xếp theo lượt ủng hộ, giúp nhóm cốt lõi chỉ báo tốt hơn về những tính năng nào có nhu cầu cao, so với các vấn đề GitHub khó phân loại hơn. Không thực hiện Yêu cầu kéo cho các tính năng mới (đặc biệt là các tính năng lớn) vì ai đó có thể đã làm việc trên nó hoặc sẽ là một phần trong lộ trình của chúng tôi. Nói chuyện với chúng tôi trước!