介绍
¥Introduction
⚡ Docusaurus 将帮助你立即创建一个漂亮的文档网站。
¥⚡️ Docusaurus will help you ship a beautiful documentation site in no time.
💸 构建定制技术堆栈非常昂贵。相反,专注于你的内容并只编写 Markdown 文件。
¥💸 Building a custom tech stack is expensive. Instead, focus on your content and just write Markdown files.
💥 准备好了解更多了吗?使用版本控制、i18n、搜索和主题自定义等高级功能。
¥💥 Ready for more? Use advanced features like versioning, i18n, search and theme customizations.
💅 检查 最佳 Docusaurus 网站 以获得灵感并阅读一些 感言。
¥💅 Check the best Docusaurus sites for inspiration and read some testimonials.
🧐 Docusaurus 是一个静态站点生成器。它构建了一个具有快速客户端导航的单页面应用,利用 React 的全部功能使你的网站具有交互性 。它提供开箱即用的文档功能,但可用于创建任何类型的网站(个人网站、产品、博客、营销登陆页面等)。
¥🧐 Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).
快速通道 ⏱️
¥Fast Track ⏱️
通过玩 5 分钟了解 Docusaurus!
¥Understand Docusaurus in 5 minutes by playing!
创建一个新的 Docusaurus 站点并遵循非常简短的嵌入式教程。
¥Create a new Docusaurus site and follow the very short embedded tutorial.
安装 Node.js 并创建一个新的 Docusaurus 站点:
¥Install Node.js and create a new Docusaurus site:
npx create-docusaurus@latest my-website classic
启动站点:
¥Start the site:
cd my-website
npx docusaurus start
打开 http://localhost:3000
并按照教程进行操作。
¥Open http://localhost:3000
and follow the tutorial.
立即在浏览器中使用 docusaurus.new 测试 Docusaurus!
¥Use docusaurus.new to test Docusaurus immediately in your browser!
或者在线阅读 5 分钟教程。
¥Or read the 5-minute tutorial online.
Docusaurus:文档变得简单
¥Docusaurus: Documentation Made Easy
在 Algolia 社区活动 的这次演讲中,Meta 开源团队 分享了 Docusaurus 的简要演练。他们介绍了如何开始项目、启用插件以及设置文档和博客等功能。
¥In this presentation at Algolia Community Event, Meta Open Source team shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.
从 v1 迁移
¥Migrating from v1
Docusaurus v2+ 完全重写了 Docusaurus v1,利用了完全现代化的工具链。v2 正式发布 之后,我们强烈建议你使用 Docusaurus v2+ 而不是 Docusaurus v1,因为 Docusaurus v1 已被弃用。
¥Docusaurus v2+ has been a total rewrite from Docusaurus v1, taking advantage of a completely modernized toolchain. After v2's official release, we highly encourage you to use Docusaurus v2+ over Docusaurus v1, as Docusaurus v1 has been deprecated.
很多用户 已经在使用 Docusaurus v2+ (趋势)。
¥A lot of users are already using Docusaurus v2+ (trends).
如果出现以下情况,请使用 Docusaurus v2+:
¥Use Docusaurus v2+ if:
-
:白色复选标记:你想要一个现代的 Jamstack 文档站点
¥✅ You want a modern Jamstack documentation site
-
:白色复选标记:你需要具有客户端路由的单页应用 (SPA)
¥✅ You want a single-page application (SPA) with client-side routing
-
:白色复选标记:你想要 React 和 MDX 的全部功能
¥✅ You want the full power of React and MDX
-
:白色复选标记:你不需要 IE11 支持
¥✅ You do not need support for IE11
如果是以下情况,请使用 Docusaurus v1:
¥Use Docusaurus v1 if:
-
❌你不需要单页应用 (SPA)
¥❌ You don't want a single-page application (SPA)
-
❌你需要 IE11 的支持(...是吗?IE 已经达到使用寿命 不再受到官方支持)
¥❌ You need support for IE11 (...do you? IE has already reached end-of-life and is no longer officially supported)
对于想要升级到 v2+ 的现有 v1 用户,你可以关注我们的 迁移指南。
¥For existing v1 users that are seeking to upgrade to v2+, you can follow our migration guides.
特性
¥Features
Docusaurus 的构建高度重视开发者和贡献者的体验。
¥Docusaurus is built with high attention to the developer and contributor experience.
-
⚛️ 使用 💚 和 React 构建:
¥⚛️ Built with 💚 and React:
-
使用 React 进行扩展和定制
¥Extend and customize with React
-
通过提供你自己的 React 组件来完全控制你网站的浏览体验
¥Gain full control of your site's browsing experience by providing your own React components
-
-
🔌 插件化:
¥🔌 Pluggable:
-
使用基本模板引导你的网站,然后使用高级功能和插件
¥Bootstrap your site with a basic template, then use advanced features and plugins
-
开源你的插件以与社区分享
¥Open source your plugins to share with the community
-
-
✂️ 开发者经验:
¥✂️ Developer experience:
-
立即开始编写你的文档
¥Start writing your docs right now
-
通用配置入口点,使其更易于贡献者维护
¥Universal configuration entry point to make it more maintainable by contributors
-
通过快速增量构建进行热重载更改
¥Hot reloading with lightning-fast incremental build on changes
-
基 于路由的代码和数据拆分
¥Route-based code and data splitting
-
轻松发布到 GitHub Pages、Netlify、Vercel 和其他部署服务
¥Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease
-
我们的共同目标是帮助你的用户快速找到他们需要的东西并更好地了解你的产品。我们分享最佳实践,帮助你正确、良好地构建文档网站。
¥Our shared goal—to help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well.
-
🎯 SEO 友好:
¥🎯 SEO friendly:
-
HTML 文件是为每个可能的路径静态生成的。
¥HTML files are statically generated for every possible path.
-
特定于页面的 SEO 可帮助你的用户找到直接与他们手头的问题相关的官方文档。
¥Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
-
-
📝 由 MDX 提供支持:
¥📝 Powered by MDX:
-
通过嵌入 Markdown 中的 JSX 和 React 编写交互式组件。
¥Write interactive components via JSX and React embedded in Markdown.
-
在在线编辑器中分享你的代码,让你的用户当场爱上你的产品。
¥Share your code in live editors to get your users to love your products on the spot.
-
-
🔍 搜索:你的完整网站是可搜索的。
¥🔍 Search: Your full site is searchable.
-
💾 文档版本控制:帮助你使文档与项目版本保持同步。
¥💾 Document Versioning: Helps you keep documentation in sync with project releases.
-
🌍 国际化(i18n):将你的网站翻译为多种语言环境。
¥ 🌍 Internationalization (i18n): Translate your site in multiple locales.
Docusaurus v2+ 生来就适合所有用户使用,并且速度快如闪电。
¥Docusaurus v2+ is born to be compassionately accessible to all your users, and lightning-fast.
-
⚡ 快如闪电。Docusaurus v2+ 遵循 PRPL 模式,确保你的内容加载速度极快。
¥⚡️ Lightning-fast. Docusaurus v2+ follows the PRPL Pattern that makes sure your content loads blazing fast.
-
🦖 无障碍。关注可访问性,使所有用户都可以平等地访问你的网站。
¥🦖 Accessible. Attention to accessibility, making your site equally accessible to all users.
设计原则
¥Design principles
-
学的东西很少。Docusaurus 应该易于学习和使用,因为 API 非常小。大多数事情仍然是用户可以实现的,即使需要花费更多的代码和更多的时间来编写。没有抽象比有错误的抽象更好,我们不希望用户不得不绕过错误的抽象。强制谈话 - 最小 API 表面积。
¥Little to learn. Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk—Minimal API Surface Area.
-
直觉的。用户在查看 Docusaurus 项目的项目目录或添加新功能时不会感到不知所措。它应该看起来直观且易于使用他们熟悉的方法进行构建。
¥Intuitive. Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
-
分层架构。我们堆栈的每一层(内容/主题/样式)之间的关注点分离应该是清晰的 - 充分抽象和模块化。
¥Layered architecture. The separations of concerns between each layer of our stack (content/theming/styling) should be clear—well-abstracted and modular.
-
合理的默认值。将为用户完成常见和流行的性能优化和配置,但他们可以选择覆盖它们。
¥Sensible defaults. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
-
没有供应商锁定。尽管强烈鼓励用户使用默认插件或 CSS,但并不要求用户使用默认插件或 CSS。某些核心基础设施(例如 React Loadable 和 React Router)无法交换,因为我们对它们进行了默认性能优化,但没有对更高级别的进行优化。Markdown 引擎、CSS 框架、CSS 方法论和其他架构的选择将完全取决于用户。
¥No vendor lock-in. Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core infrastructures like React Loadable and React Router cannot be swapped because we do default performance optimization on them, but not higher-level ones. Choice of Markdown engines, CSS frameworks, CSS methodology, and other architectures will be entirely up to users.
我们相信,作为开发者,了解库的工作原理有助于我们更好地使用它。因此,我们致力于解释 Docusaurus 的架构和各个组件,希望阅读它的用户能够更深入地了解该工具并更加熟练地使用它。
¥We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
与其他工具的比较
¥Comparison with other tools
在所有静态站点生成器中,Docusaurus 独特地关注文档站点,并具有许多开箱即用的功能。
¥Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
我们还研究了其他主要的静态站点生成器,并希望分享我们对比较的见解,希望能帮助你浏览各种选择。
¥We've also studied other main static site generators and would like to share our insights on the comparison, hopefully helping you navigate through the prismatic choices out there.
Gatsby
Gatsby 包含大量功能,拥有丰富的插件生态系统,并且能够完成 Docusaurus 所做的一切。当然,这是以更高的学习曲线为代价的。Gatsby 在很多方面都做得很好,适合构建多种类型的网站。另一方面,Docusaurus 试图把一件事做得超级好 - 成为编写和发布内容的最佳工具。
¥Gatsby is packed with a lot of features, has a rich ecosystem of plugins, and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
GraphQL 也是 Gatsby 的核心,尽管你不一定需要 GraphQL 来构建 Gatsby 站点。在大多数情况下,构建静态网站时,你不需要 GraphQL 提供的灵活性。
¥GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.
Docusaurus v2+ 的许多方面都受到了 Gatsby 最好的东西的启发,它是一个很好的选择。
¥Many aspects of Docusaurus v2+ were inspired by the best things about Gatsby and it's a great alternative.
Docz 是一个用于构建文档网站的 Gatsby 主题。目前它的特性不如 Docusaurus。
¥Docz is a Gatsby theme to build documentation websites. It is currently less featured than Docusaurus.
Next.js
Next.js 是另一个非常流行的混合 React 框架。它可以帮助你构建一个良好的文档网站,但它对文档用例并不有态度,并且需要做更多的工作来实现 Docusaurus 提供的开箱即用的功能。
¥Next.js is another very popular hybrid React framework. It can help you build a good documentation website, but it is not opinionated toward the documentation use-case, and it will require a lot more work to implement what Docusaurus provides out-of-the-box.
Nextra 是一个基于 Next.js 构建的有态度的静态站点生成器。目前它的特性不如 Docusaurus。
¥Nextra is an opinionated static site generator built on top of Next.js. It is currently less featured than Docusaurus.
VitePress
VitePress 与 Docusaurus 有很多相似之处 - 两者都重点关注以内容为中心的网站,并提供开箱即用的定制文档功能。然而,VitePress 由 Vue 提供支持,而 Docusaurus 由 React 提供支持。如果你想要一个基于 Vue 的解决方案,VitePress 将是一个不错的选择。
¥VitePress has many similarities with Docusaurus - both focus heavily on content-centric websites and provides tailored documentation features out of the box. However, VitePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VitePress would be a decent choice.
MkDocs
MkDocs 是一个流行的 Python 静态站点生成器,其价值主张与 Docusaurus 类似。
¥MkDocs is a popular Python static site generator with value propositions similar to Docusaurus.
如果你不需要单页应用并且不打算利用 React,那么这是一个不错的选择。
¥It is a good option if you don't need a single-page application and don't plan to leverage React.
适用于 MkDocs 的 Material 是一个漂亮的主题。
¥Material for MkDocs is a beautiful theme.
Docsify
Docsify 可以轻松创建文档网站,但不是静态网站生成器,也不利于 SEO。
¥Docsify makes it easy to create a documentation website, but is not a static-site generator and is not SEO friendly.
GitBook
GitBook 具有非常简洁的设计,并已被许多开源项目使用。随着其重点转向商业产品而不是开源工具,它的许多要求不再满足开源项目文档站点 的需求。结果,许多人转向其他产品。你可以在 此处 阅读有关 Redux 切换到 Docusaurus 的信息。
¥GitBook has a very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs of open source projects' documentation sites. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus here.
目前,GitBook 仅对开源和非营利团队免费。Docusaurus 对所有人免费。
¥Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
Jekyll
Jekyll 是最成熟的静态站点生成器之一,并且一直是一个很好用的工具 - 事实上,在 Docusaurus 之前,Facebook 的大多数开源网站都是基于 Jekyll 构建的!上手非常简单。我们希望为开发者带来与使用 Jekyll 构建静态站点类似的体验。
¥Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
与静态生成的 HTML 和使用 <script />
标签添加的交互性相比,Docusaurus 网站是 React 应用。使用现代 JavaScript 生态系统工具,我们希望在文档网站的性能、资源构建管道和优化以及易于设置方面制定新标准。
¥In comparison with statically generated HTML and interactivity added using <script />
tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites' performance, asset building pipeline and optimizations, and ease to set up.
随时了解情况
¥Staying informed
缺少什么吗?
¥Something missing?
如果你发现文档存在问题,或者对如何改进文档或项目有建议,请为我们 提出问题,或发送一条提及 @docusaurus Twitter 账户的推文。
¥If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please file an issue for us, or send a tweet mentioning the @docusaurus Twitter account.
对于新功能请求,你可以在我们的 功能请求板(Canny) 上创建帖子,这是一个方便的路由图工具,并允许按点赞数排序,与 GitHub 相比,这可以让核心团队更好地了解哪些功能需求量较大 更难分类的问题。避免对新功能(尤其是大型功能)提出 Pull 请求,因为有人可能已经在开发它或将成为我们路由图的一部分。先和我们谈谈吧!
¥For new feature requests, you can create a post on our feature requests board (Canny), which is a handy tool for road-mapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!