跳转至主内容
Version: 2.0.0-beta.0

介绍

⚡️ Docusaurus will help you ship a beautiful documentation site in no time.

💸 Building a custom tech stack is expensive. Instead, focus on your content and just write Markdown files.

💥 Ready for more? Use advanced features like versioning, i18n, search and theme customizations.

💅 Check the best Docusaurus sites for inspiration and read some testimonials.

🧐 Docusaurus is a static-site generator. It builds a single-page application with a 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).

Docusaurus Slash 简介

Fast Track ⏱️#

Understand Docusaurus in 5 minutes by playing!

Create a new Docusaurus site and follow the very short embedded tutorial.

Install Node.js and create a new Docusaurus site:

npx @docusaurus/[email protected] init my-website classic

Start the site:

cd my-website
npx docusaurus start

Open http://localhost:3000 and follow the tutorial.

tip

使用 new.docusaurus.io 以即刻在你的浏览器中测试 Docusaurus!

Or read the 5 minutes tutorial online.

声明#

Docusaurus v2 is beta but already quite stable and widely used.

We highly encourage you to use Docusaurus v2 over Docusaurus v1, as Docusaurus v1 will be deprecated soon.

A lot of users are already using Docusaurus v2 (trends).

若您有以下需求,请使用 Docusaurus v2:

  • ✅ 您想要现代化的 Jamstack 开发文档网站
  • ✅ 您想要自带客户端路由的单页应用 (SPA)
  • ✅ 您想要发挥 React 和 MDX 的全部功力
  • ✅ 您不需要支持 IE11

若您有以下需求,请使用 Docusaurus v1

  • ❌ 您不需要单页应用 (SPA)
  • ❌ 您需要支持 IE11

特性#

Docusaurus is built with high attention to the developer and contributor experience.

  • ⚛️ 用 💚 使用 React 打造
    • 使用 React 扩展与自定义
    • Gain full control of your site's browsing experience by providing your own React components
  • 可扩展
    • Bootstrap your site with a basic template, then use advanced features and plugins
    • Open source your plugins to share with the community
  • ✂️ 开发者体验
    • Start writing your docs right now
    • 统一配置文件可被轻松维护
    • 更改后飞速增量编译并热加载
    • 基于路由的代码及数据拆分
    • Publish to GitHub Pages, Netlify, Vercel and other deployment services with ease

我们的共同目标——快速让用户找到其所需并更好地了解您的产品。 We share with you our best practices helping you build your doc site right and well.

  • 🎯 SEO 友好
    • 为每条路径静态生成 HTML 文件
    • 指定页面 SEO 来帮助您的用户快速查阅官方以解决现有问题
  • 📝 MDX 驱动
    • 使用 JSX 及 React 撰写交互组件并嵌入 Markdown 文本
    • 在实时编辑器中分享您的代码让您的用户爱您所写
  • 🔍 搜索 - 全站均可被搜索
  • 💾 文档分版 - 帮助您的项目发行及文档保持同步。
  • 🌍 i18n - Translate your site in multiple locales

Docusaurus 2 生而乐意为您的用户服务,而且快如闪电。.

  • ⚡️ 快如闪电 - Docusaurus 2 遵循 PRPL 模式来确保您的内容被快速加载
  • 🦖 无障碍 - 着重无障碍,所有用户均能轻松使用

Design principles#

  • 简单易用 - Docusaurus 应简单易用,暴露最少限度的 API。 即使需要花大量时间写更多代码,大多数功能应仍可由用户完成。 没有抽象比错误抽象更好,我们不希望用户去捣鼓错误的抽象。 必看讲座 - 最少限度的 API 表面.
  • 自然直观 - 用户查看 Docusaurus 项目目录或添加新特性时不会感到头昏脑胀。 软件应简单直观,用户则可轻松扩展。
  • 分层架构 - 软件栈的分层(内容/主题/样式)应一目了然 - 充分抽象并模块化。
  • 智能默认 - 为用户自动完成常见、热门的性能优化选项,并提供手动覆盖的方式。
  • 不受约束 - 用户无需使用默认插件或 CSS(虽然强烈推荐)。 由于我们进行了默认的性能优化,部分如 React Loadable、React Router 的低级组件无法被替换。 但包括 Markdown 引擎、CSS 框架及方法在内的高层级的组件完全由您掌控。

我们作为开发者相信,了解一个库的运作方式可以让我们更加得心应手地使用它。 因此,我们致力于诠释 Docusaurus 的架构及多个组件,希望用户能更深入地了解并熟练使用此工具。

与其他工具的对比#

Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.

我们还研究了其他主流的静态网站生成器并想向您分享我们的拙见,希望能帮助您从多种工具中做出选择。

Gatsby#

Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. 当然,这带来了较高的学习曲线。 Gatsby 在许多方面做得都很出色,且适合构建许多类型的网站。 另一方面,Docusaurus 尝试将一件事做到尽善尽美——成为最好的内容撰写及发布工具。

GraphQL 是 Gatsby 的核心,虽然您并不需要它来构建一个站点。 在构建静态网站的多数情况下,您不需要 GraphQL 所提供的灵活性。

Docusaurus 2 的许多方面都被 Gatsby 的出色之处所启发,这是一个优秀的替代品。

Dokz is a Gatsby theme to build documentation website. It is currently less featured than Docusaurus.

Next.js#

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 is an opinionated static-site-generator built on top of Next.js. It is currently less featured than Docusaurus.

VuePress#

VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. 但是,VuePress 由 Vue 驱动,而 Docusaurus 则是由 React 驱动。 若您想要基于 Vue 的解决方案,这将是您的不二之选。

MkDocs#

MkDocs is a popular Python static-site-generator with value proposition similar to Docusaurus.

It is a good option if you don't need a single-page application, and don't plan to leverage React.

Material for MkDocs is a beautiful theme.

Docsify#

Docsify makes it easy to create a documentation website, but is not a static-site generator and is not SEO friendly.

GitBook#

GitBook has very clean design and has been used by many open source projects. 而随着其中心逐渐转向商业产品而非开源工具,它的许多需求不再符合一个开源项目网站的需要。 结果就是,许多项目转用了其他产品。 您也许在此处听说过 Redux 转投 Docusaurus 怀抱的事情。

目前,GitBook 仅向开源及非营利团队提供。 Docusaurus 则对所有人免费。

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! 它的上手难度极低。 我们想要为您带来与使用 Jekyll 构建静态站点类似的开发者体验。

同静态生成的 HTML 及使用 <script /> 标签所添加的交互性相比,Docusaurus 站点为 React 应用程序。 我们希望借由现代化 JavaScript 生态系统工具,为文档站点性能、资源构建管道及优化和易部署性制定新标准。

保持更新#

缺点什么?#

若您发现文档问题或有改进文档或项目的建议,请向我们提出议题,或在 Twitter 上 @docusaurus

要提议新功能,您可以在我们的 Canny 板块上发帖。相较 GitHub 议案功能,此工具的点赞功能可让核心团队轻易了解高需求的功能特性,并做出项目的未来规划。 请尽量避免提交新功能的合并请求 (Pull Request),我们可能已有专人正在处理,或有可能此功能已经是我们未来规划的一部分。 总之,请先联系我们!