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

介绍

⚡️ Docusaurus 将助您在极短时间内搭建优美的文档网站

💸 自己造轮子是一件苦差事。 现在,您可以专注于内容创作,仅需编写 Markdown 文件即可。

💥 想深入了解吗? 来试试如文档分版、本地化、自定义搜索及主题在内的进阶功能特性吧!

💅 看看最佳的 Docusaurus 网站来获取灵感,并读读其他人的使用感言吧!

🧐 Docusaurus 是一款静态站点生成器。 我们释放了 React 的全部潜能,搭建了这款带有快速的客户端导航且交互性极佳的单页应用。 即开即用的文档功能不仅仅局限于文档本身,还可用于创建任何类型的网站(个人网站、产品网站、博客、营销着陆页等)。

Docusaurus Slash 简介

快速通道 ⏱️#

边玩边学 Docusaurus,仅需 5 分钟

创建新的 Docusaurus 站点,并遵循极为简短的内嵌教程。

安装 Node.js,并创建新的 Docusaurus 站点:

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

运行网站:

cd my-websitenpx docusaurus start

打开 http://localhost:3000 并遵循教程。

tip

Use docusaurus.new to test Docusaurus immediately in your browser!

Or read the 5 minutes tutorial online.

声明#

Docusaurus v2 正处于 Beta 阶段,但已十分稳定且被广泛使用。

我们强烈推荐您使用 Docusaurus v2 替代即将废弃的 Docusaurus v1

目前,已有大量用户在使用 Docusaurus v2(使用趋势)。

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

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

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

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

特性#

Docusaurus 设计之初就极度重视开发者及贡献者的体验。

  • ⚛️ 用 💚 使用 React 打造
    • 使用 React 扩展与自定义
    • 提供您自己的 React 组件,完全掌控网站的浏览体验
  • 可扩展
    • 使用基础模板搭建网站,随后使用进阶功能及插件
    • 开放您的插件源码,与社群共享
  • ✂️ 开发者体验
    • 立即撰写您的软件文档
    • 统一配置文件可被轻松维护
    • 更改后飞速增量编译并热加载
    • 基于路由的代码及数据拆分
    • 轻松发布至 GitHub Pages、Netlify、Vercel 及其他部署服务

我们的共同目标——快速让用户找到需要的内容,并更好地了解您的产品。 我们将与您分享我们的最佳实践,帮助您正确构建自己的文档网站。

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

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

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

设计理念#

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

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

与其他工具的对比#

在所有的静态网站生成器中,Docusaurus 独树一帜,专注于文档站点且有着您需要的诸多开箱即用功能。

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

Gatsby#

Gatsby 自带诸多功能,且拥有丰富的插件生态,足于胜任 Docusaurus 的所有功能。 当然,这带来了较高的学习曲线。 Gatsby 在许多方面做得都很出色,且适合构建许多类型的网站。 另一方面,Docusaurus 尝试将一件事做到尽善尽美——成为最好的内容撰写及发布工具。

GraphQL 是 Gatsby 的核心,但您并不需要它来构建一个站点。 而在大多数静态网站中,您更不需要 GraphQL 所提供的灵活性。

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

Docz 是一款用于构建文档站点的 Gatsby 主题。 它的功能与 Docusaurus 相比要匮乏。

Next.js#

Next.js 是另一款极为热门的 React 混合框架。 它可以帮助您构建出色的文档站点,但并不着重于文档功能本身,而且需要您手动实现 Docusaurus 所自带的功能。

Nextra 是一款基于 Next.js 的静态站点生成器。 它的功能与 Docusaurus 相比要匮乏。

VuePress#

VuePress 与 Docusaurus 有着许多共同点——都非常专注于以内容为中心的网站,且都在安装后提供量身定制的文档特性。 但是,VuePress 由 Vue 驱动,而 Docusaurus 则是由 React 驱动。 若您想要基于 Vue 的解决方案,这将是您的不二之选。

MkDocs#

MkDocs 是一款受欢迎的 Python 静态站点生成器,其设计理念与 Docusaurus 类似。

若您不需要单页应用,或是 React 的话,这将是您的不二之选。

Material for MkDocs 是一款很好看的主题。

Docsify#

Docsify 让您能轻松创建文档网站,但其并不是一款静态网站生成器,且未经搜索引擎优化。

GitBook#

GitBook 的设计清爽,诸多开源项目都在使用。 而随着其中心逐渐转向商业产品而非开源工具,它的许多需求不再符合一个开源项目网站的需要。 结果就是,许多项目转用了其他产品。 您也许在此处听说过 Redux 转投 Docusaurus 怀抱的事情。

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

Jekyll#

Jekyll 是现有的一款成熟且优秀的静态网站生成器——实际上,在 Docusaurus 诞生之前,Facebook 的诸多开源站点都是使用 Jekyll 构建而成! 它的上手难度极低。 我们想要为您带来与使用 Jekyll 构建静态站点类似的开发者体验。

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

保持更新#

缺点什么?#

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

For new feature requests, you can create a post on our feature requests board (Canny), which is a handy tool for roadmapping 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. 请尽量避免提交新功能的合并请求 (Pull Request),我们可能已有专人正在处理,或有可能此功能已经是我们未来规划的一部分。 总之,请先联系我们!