1、介绍
docusaurus介绍
目录
[toc]
官网
中文:https://www.docusaurus.cn (这个中文版不太友好,里面好多汉化不完整)
推荐(汉化完整版)https://docusaurus.nodejs.cn/
https://docusaurus.nodejs.cn/与https://docusaurus.io/zh-CN/ 网站有啥区别吗?
这两个网站均提供 Docusaurus 的中文 文档,但它们之间有一些区别:
-
官方源头:
- https://docusaurus.io/zh-CN/ 是 Docusaurus 的官方主站的中文版本,直接由 Docusaurus 团队维护。它是 Docusaurus 的主要文档站点,通常会包含最新的功能和更新。
-
中文社区支持:
- https://docusaurus.nodejs.cn/ 是由 Node.js 中文社区维护的 Docusaurus 中文网站,可能会包含社区贡献的内容和示例。这意味着它可能包括更多的实用案例和中文用户的经验分享。
-
内容更新频率:
- 主站的中文版本更新频率可能与英文版本同步,而社区站点的更新速度可能会有所不同,具体取决于社区的活跃程度。
-
风格和布局:
- 两者的设计和布局可能会有所不同,虽然目的相同,但可能在视觉和用户体验上存在差异。
总结
总体来说,如果你想获得最新的官方信息,建议访问 **https://docusaurus.io/zh-CN/**。如果你希望看到更多社区支持的内容或实例,可以访问 **https://docusaurus.nodejs.cn/**。两者都可以作为学 习和使用 Docusaurus 的有效资源。
- github 上有 55.2K 个 star
https://github.com/facebook/docusaurus
截止:2024年9月1日
简介
⚡ Docusaurus 将帮助你立即创建一个漂亮的文档网站。
💸 构建定制技术堆栈非常昂贵。相反,专注于你的内容并只编写 Markdown 文件。
💥 准备好了解更多了吗?使用版本控制、i18n、搜索和主题自定义等高级功能。
💅 检查 最佳 Docusaurus 网站 以获得灵感并阅读一些 感言。
🧐 Docusaurus 是一个静态站点生成器。它构建了一个具有快速客户端导航的单页面应用,利用 React 的全部功能使你的网站具有交互性。它提供开箱即用的文档功能,但可用于创建任何类型的网站(个人网站、产品、博客、营销登陆页面等)。
特性
Docusaurus 的构建高度重视开发者和贡献者的体验。
- ⚛️ 使用 💚 和 React 构建:
- 使用 React 进行扩展和定制
- 通过提供你自己的 React 组件来完全控制你网站的浏览体验
- 🔌 插件化:
- 使用基本模板引导你的网站,然后使用高级功能和插件
- 开源你的插件以与社区分享
- ✂️ 开发者经验:
- 立即开始编写你的文档
- 通用配置入口点,使其更易于贡献者维护
- 通过快速增量构建进行热重载更改
- 基于路由的代码和数据拆分
- 轻松发布到 GitHub Pages、Netlify、Vercel 和其他部署服务
我们的共同目标是帮助你的用户快速找到他们需要的东西并更好地了解你的产品。我们分享最佳实践,帮助你正确、良好地构建文档网站。
- 🎯 SEO 友好:
- HTML 文件是为每个可能的路径静态生成的。
- 特定于页面的 SEO 可帮助你的用户找到直接与他们手头的问题相关的官方文档。
- 📝 由 MDX 提供支持:
- 通过嵌入 Markdown 中的 JSX 和 React 编写交互式组件。
- 在在线编辑器中分享你的代码,让你的用户当场爱上你的产品。
- 🔍 搜索:你的完整网站是可搜索的。
- 💾 文档版本控制:帮助你使文档与项目版本保持同步。
- 🌍 国际化(i18n):将你的网站翻译为多种语言环境。
Docusaurus v2+ 生来就适合所有用户使用,并且速度快如闪电。
- ⚡ 快如闪电。Docusaurus v2+ 遵循 PRPL 模式,确保你的内容 加载速度极快。
- 🦖 无障碍。关注可访问性,使所有用户都可以平等地访问你的网站。
设计原则
- 学的东西很少。Docusaurus 应该易于学习和使用,因为 API 非常小。大多数事情仍然是用户可以实现的,即使需要花费更多的代码和更多的时间来编写。没有抽象比有错误的抽象更好,我们不希望用户不得不绕过错误的抽象。强制谈话 - 最小 API 表面积。
- 直觉的。用户在查看 Docusaurus 项目的项目目录或添加新功能时不会感到不知所措。它应该看起来直观且易于使用他们熟悉的方法进行构建。
- 分层架构。我们堆栈的每一层(内容/主题/样式)之间的关注点分离应该是清晰的 - 充分抽象和模块化。
- 合理的默认值。将为用户完成常见和流行的性能优化和配置,但他们可以选择覆盖它们。
- 没有供应商锁定。尽管强烈鼓励用户使用默认插件或 CSS,但并不要求用户使用默认插件或 CSS。某些核心基础设施(例如 React Loadable 和 React Router)无法交换,因为我们对它们进行了默认性能优化,但没有对更高级别的进行优化。Markdown 引擎、CSS 框架、CSS 方法论和其他架构的选择将完全取决于用户。
我们相信,作为开发者,了解库的工作原理有助于我们更好地使用它。因此,我们致力于解释 Docusaurus 的架构和各个组件,希望阅读它的用户能够更深入地了解该工具并更加熟练地使用它。
使用场 景
-
使用 markdown 语法书写静态博客;
-
构建一个文档类的站点;
-
一个带有新闻功能和静态页面为主的官方网站;
-
建立一个实时代码演示效果的教程类的网站;
-
集成搜索的个人知识库;
-
知识库+博客 2合一的丝滑解决方案;
与其他工具的比较
在所有静态站点生成器中,Docusaurus 独特地关注文档站点,并具有许多开箱即用的功能。
我们还研究了其他主要的静态站点生成器,并希望分享我们对比较的见解,希望能帮助你浏览各种选择。
Gatsby
Gatsby 包含大量功能,拥有丰富的插件生态系统,并且能够完成 Docusaurus 所做的一切。当然,这是以更高的学习曲线为代价的。Gatsby 在很多方面都做得很好,适合构建多种类型的网站。另一方面,Docusaurus 试图把一件事做得超级好 - 成为编写和发布内容的最佳工具。
GraphQL 也是 Gatsby 的核心,尽管你不一定需要 GraphQL 来构建 Gatsby 站点。在大多数情况下,构建静态网站时,你不需要 GraphQL 提供的灵活性。
Docusaurus v2+ 的许多方面都受到了 Gatsby 最好 的东西的启发,它是一个很好的选择。
Docz 是一个用于构建文档网站的 Gatsby 主题。目前它的特性不如 Docusaurus。
Next.js
Next.js 是另一个非常流行的混合 React 框架。它可以帮助你构建一个良好的文档网站,但它对文档用例并不有态度,并且需要做更多的工作来实现 Docusaurus 提供的开箱即用的功能。
Nextra 是一个基于 Next.js 构建的有态度的静态站点生成器。目前它的特性不如 Docusaurus。
VitePress
VitePress 与 Docusaurus 有很多相似之处 - 两者都重点关注以内容为中心的网站,并提供开箱即用的定制文档功能。然而,VitePress 由 Vue 提供支持,而 Docusaurus 由 React 提供支持。如果你想要一个基于 Vue 的解决方案,VitePress 将是一个不错的选择。
MkDocs
MkDocs 是一 个流行的 Python 静态站点生成器,其价值主张与 Docusaurus 类似。
如果你不需要单页应用并且不打算利用 React,那么这是一个不错的选择。
适用于 MkDocs 的 Material 是一个漂亮的主题。
Docsify
Docsify 可以轻松创建文档网站,但不是静态网站生成器,也不利于 SEO。
GitBook
GitBook 具有非常简洁的设计,并已被许多开源项目使用。随着其重点转向商业产品而不是开源工具,它的许多要求不再满足开源项目文档站点的需求。结果,许多人转向其他产品。你可以在 此处 阅读有关 Redux 切换到 Docusaurus 的信息。
目前,GitBook 仅对开源和非营利团队免费。Docusaurus 对所有人免费。
Jekyll
Jekyll 是最成熟的静态站点生成器之一,并且一 直是一个很好用的工具 - 事实上,在 Docusaurus 之前,Facebook 的大多数开源网站都是基于 Jekyll 构建的!上手非常简单。我们希望为开发者带来与使用 Jekyll 构建静态站点类似的体验。
与静态生成的 HTML 和使用 <script />
标签添加的交互性相比,Docusaurus 网站是 React 应用。使用现代 JavaScript 生态系统工具,我们希望在文档网站的性能、资源构建管道和优化以及易于设置方面制定新标准。
汇总
比较
vuepress、vitepress、docusaurus中哪个更适合作为文档知识库,请输出一个表格来比较两者的区别,并给出建议
VuePress、VitePress 和 Docusaurus 都是非常强大的静态站点生成器,特别适合用于构建文档网站。以下是一个比较表格,列出了这三者的一些关键区别:
特性/功能 | VuePress | VitePress | Docusaurus |
---|---|---|---|
开发语言 | Vue.js 2 | Vue.js 3 + Vite | React |
渲染引擎 | Webpack | Vite | Webpack |
启动时间 | 相对较慢 | 快速 | 中等 |
构建速度 | 中等 | 快速 | 中等 |
默认主题 | 简洁,适合文档 | 简洁,适合文档 | 功能丰富,适合文档和博客 |
主题系统 | 支持自定义主题 | 支持自定义主题 | 支持自定义主题 |
生态系统 | 插件生态丰富 | 插件生态逐渐增长 | 插件生态丰富 |
插件系统 | 提供多种官方插件和社区插件 | 插件生态尚在发展中 | 提供多种官方插件和社区插件 |
文档结构 | 基于文件系统 | 基于文件系统 | 基于文件系统 |
导航 | 支持侧边栏和导航栏 | 支持侧边栏和导航栏 | 支持侧边栏和导航栏 |
多语言支持 | 内置支持 | 内置支持 | 内置支持 |
SEO | 原生支持基本SEO优化 | 原生支持基本SEO优化 | 原生支持基本SEO优化 |
部署方式 | 静态部署,支持GitHub Pages等 | 静态部署,支持GitHub Pages等 | 静态部署,支持GitHub Pages等 |
定制化难度 | 中等,需要了解Vue.js | 中等,需要了解Vue.js | 中等,需要了解React |
热更新支持 | 支持,但启动较慢 | 支持,启动快速 | 支持,启动速度中等 |
文档搜索 | 支持 | 支持 | 支持 |
静态文件热更新 | 不支持 | 支持 | 支持 |
代码高亮 | 默认使用 Prism | 默认使用 Prism | 默认使用 Prism |
易用性 | 中等,需要熟悉Vue.js | 高,需要熟悉Vue.js 3 和 Vite | 中等,需要熟悉React |
版本管理 | 支持插件 | 支持插件 | 内置支持 |
默认首页 | 提供首页简介 | 提供首页简介 | 提供首页简介,带有更多组件和功能 |
社区活跃度 | 活跃 | 逐渐增长 | 非常活跃 |
文档和教程 | 丰富,中文支持好 | 丰富,中文支持好 | 丰富,英文为主 |
迁移成本 | 从VuePress迁移到VitePress相对容易 | 从VuePress迁移到VitePress相对容易 | 从其他平台迁移相对较高 |
特色功能 | 支持Markdown增强 | 支持Markdown增强 | 支持MDX(Markdown + JSX),博客功能强大 |
适用场景 | 适合已经有Vue.js 2的项目,或简单文档站点 | 适合新项目,关注性能和启动速度的用户 | 适合复杂文档和博客网站,或已有React项目 |
建议
-
VuePress:
- 优点:适合已经熟悉Vue.js 2的开发者,插件生态丰富。
- 缺点:启动时间相对较慢,未来可能会被VitePress取代。
- 适用场景:现有Vue.js 2项目的文档或需要快速构建的简单文档站点。
-
VitePress:
- 优点:基于Vue.js 3和Vite,启动速度快,性能好。
- 缺点:插件生态还在发展中,相比VuePress功能少一些。
- 适用场景:需要高性能、快速启动的文档站点,或者新的Vue.js 3项目。
-
Docusaurus:
- 优点:功能丰富,社区活跃,适合构建复杂的文档和博客网站。
- 缺点:需要了解React,启动时间相对较慢。
- 适用场景:需要构建功能复杂、定制化需求高的文档和博客网站,或者已有React项目的文档。
总结
- 如果你已经熟悉 Vue.js 2,并且需要快速构建一个文档站点,VuePress 是一个不错的选择。
- 如果你更关注性能和启动速度,并且愿意使用 Vue.js 3,VitePress 是一个很好的选择。
- 如果你需要一个功能丰富、社区活跃的文档和博客解决方案,并且熟悉 React,那么选择 Docusaurus 是比较明智的。