快速了解Docusaurus开源项目

coverImg

文章目录

一、快速认识Docusaurus
背景
一句话介绍
技术栈
二、Docusaurus的核心能力
核心包含能力
重点关注的三个能力
多版本文档
多语言
自定义页面

一、快速认识Docusaurus

背景

Docusaurus 是 Meta 开源的一套文档网站 / 开源项目官网生成框架，核心目标就是：

用 Markdown / MDX 快速构建专业的技术文档站，同时支持版本、多语言、博客和自定义页面。

目前官方稳定版已经到 3.10.2，GitHub 约 66k+ Star，项目仍在持续维护。

GitHub：facebook/docusaurus

官网：Docusaurus 官网

关键词如下：

① React
② Markdown / MDX
③ Versioning 多版本
④ i18n 多语言
⑤ Docs + Blog + Custom Pages

一句话介绍

你可以把它理解成：

Markdown 文档
     ↓
Docusaurus
     ↓
React 静态网站
     ↓
GitHub Pages / Nginx / Vercel / Cloudflare

它不是类似 WordPress 的后台 CMS，而是典型的：

Docs as Code（文档即代码）

也就是：

Git 仓库
├── docs
├── blog
├── src
├── static
└── docusaurus.config.js

文档直接跟代码一起版本管理。

技术栈

Docusaurus 3 的核心技术体系为：

Node.js
   ↓
React
   ↓
MDX / Markdown
   ↓
Docusaurus Plugin
   ↓
Webpack / Static Generation
   ↓
HTML / CSS / JS

如果本身做：

Vue
Vite
Spring Boot

学习 Docusaurus 不会特别困难。只是它的 UI 扩展层是：

React

而不是 Vue。这也是它与 VitePress 最大的一个技术栈差异。

二、Docusaurus的核心能力

核心包含能力

能力	Docusaurus
Markdown 文档	✅
MDX	✅
文档目录 Sidebar	✅
全文搜索	✅
多版本文档	✅ 原生支持
多语言 i18n	✅ 原生支持
博客	✅ 原生支持
自定义首页	✅
自定义 React 页面	✅
自定义组件	✅
SEO	✅
Sitemap	✅
GitHub Pages	✅
静态部署	✅
深度主题定制	✅

官方本身就将 简单上手、本地化、多页面自定义 作为项目的重要能力。

重点关注的三个能力

多版本文档

官方文档：https://docusaurus.io/versions?utm_source=chatgpt.com

Docusaurus 相比很多轻量文档框架最大的优势之一。

举例项目管理可为：

BlogLoom Docs

Version
├── Next
├── 2.0
├── 1.5
└── 1.0

目录可以类似：

docs/
    introduction.md
    deploy.md

versioned_docs/
    version-1.0/
    version-1.5/

用户可以直接在右上角切换：

2.0
1.5
1.0

这非常适合未来维护：

AgentForge v1.x
AgentForge v2.x

BlogLoom v1.x
BlogLoom v2.x

Docusaurus 官方自己的网站实际上就在用这种版本机制，目前官方同时保留 3.x、2.x、1.x 文档。

多语言

例如可以做：

中文
English
日本語

对应：

/
├── docs
└── i18n
    ├── zh-Hans
    ├── en
    └── ja

最终 URL 可以设计成：

https://docs.xxx.com/
https://docs.xxx.com/en/
https://docs.xxx.com/ja/

而且不是简单翻译正文。

包括：

Navbar
Sidebar
Footer
Docs
Blog
页面文字

都可以分别国际化。

自定义页面

Docusaurus 并不限制只能写 Markdown。

比如：

docs.changlu.cloud/
├── /
│   └── 产品官网首页
│
├── /docs
│   └── 文档
│
├── /showcase
│   └── 案例
│
├── /pricing
│   └── Pricing
│
└── /blog
    └── 博客

这些页面可以直接用：

React
JSX / TSX
CSS
MDX

自己开发。它实际上是：

文档框架
+
React Web Framework

而不是单纯 Markdown 渲染器。

整理者：长路　时间：2026.9.29