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

介绍

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

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

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

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

🧐 Docusaurus 是一款静态站点生成器。 可以搭建带有快速客户端导航的单页应用,充分利用了React让你的网站具有交互能力。 它提供了开箱即用的文档功能,不过也可用于搭建各种网站(个人网站,产品,博客,营销登陆页,等)。

Docusaurus Slash 简介

快速通道 ⏱️

边玩边学 Docusaurus,仅需 5 分钟

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

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

npx [email protected] my-website classic

运行网站:

cd my-website
npx docusaurus start

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

tip

直接访问 docusaurus.new 来体验 Docusaurus 运行示例!

或者在线阅读5分钟教程

Docusaurus: Documentation Made Easy

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.

声明

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

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

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

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

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

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

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

特性

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

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

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 友好
    • HTML files are statically generated for every possible path.
    • Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
  • 📝 由 MDX 驱动
    • 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.
  • 🔍 搜索:全站均可被搜索。
  • 💾 Document Versioning: Helps you keep documentation in sync with project releases.
  • 🌍 国际化(i18n):将您的网站翻译至多国语言。

Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast.

  • ⚡️ Lightning-fast. Docusaurus 2 follows the PRPL Pattern that makes sure your content loads blazing fast.
  • 🦖 Accessible. Attention to accessibility, making your site equally accessible to all users.

设计理念

  • 低学习成本。 Docusaurus应该容易学习和使用,因为API非常小。 即使需要花大量时间写更多代码,大多数功能应仍可由用户完成。 没有抽象比错误抽象更好,我们不希望用户去捣鼓错误的抽象。 Mandatory talk—Minimal API Surface Area.
  • 直观易懂。 用户查看 Docusaurus 项目目录或添加新特性时不会感到头昏脑胀。 软件应简单直观,用户则可轻松扩展。
  • 分层结构。 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.
  • 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 的各种组件,希望用户可以阅读对这个工具获得更深的理解并且更为熟练地使用它。

与其他工具的对比

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

我们同时也研究了其他一些主流静态站点生成器,想与您一起分享我们比较后的看法,希望能帮您在多种选择中做出判断。

Gatsby

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

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

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

Docz 是一个 Gastsby 主题,用以搭建文档网站。 它的功能与 Docusaurus 相比要匮乏。

Next.js

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

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

VuePress

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

MkDocs

MkDocs 是一款受欢迎的 Python 静态站点生成器,其设计理念与 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 是一款很好看的主题。

Docsify

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

GitBook

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

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

Jekyll

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

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

保持更新

缺点什么?

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

对于新功能请求,您可以在我们的 功能请求板 (Canny) 上创建一个帖子, 它是一个便捷的路线图制作工具,允许通过升序排序, 与 GitHub issue 相比,核心小组能够更好地了解到什么新功能的需求更高,而 GitHub issue 更难标明这点。 请尽量避免提交新功能的合并请求 (Pull Request),我们可能已有专人正在处理,或有可能此功能已经是我们未来规划的一部分。 总之,请先联系我们!