Docusaurus 文档框架¶

一句话概述：Docusaurus 是 Meta（Facebook）开源的文档网站生成器，基于 React，内置版本管理和国际化，适合大型项目文档。

核心知识点¶

概念	白话解释
Docusaurus	Meta 出品的文档框架 = React 驱动的文档网站
MDX	加强版 Markdown = 可以在 Markdown 里写 React 组件
Versioning	版本管理 = 同时维护多个版本的文档
i18n	国际化 = 一套文档支持多种语言
Sidebar	侧边栏 = 自动或手动生成的导航菜单
Plugin	插件 = 扩展博客/搜索/分析等功能

安装配置¶

# 前置要求：Node.js >= 18
node -v                                               # 检查 Node 版本

# 创建新项目
npx create-docusaurus@latest my-docs classic           # 用经典模板创建
cd my-docs                                            # 进入项目

# 启动开发服务器
npm start                                             # 本地预览（http://localhost:3000）

# 项目结构
# my-docs/
# ├── blog/                                           # 博客文章
# ├── docs/                                           # 文档目录
# │   └── intro.md                                    # 文档首页
# ├── src/                                            # React 组件
# │   └── pages/                                      # 自定义页面
# ├── static/                                         # 静态资源
# ├── docusaurus.config.js                            # 主配置文件
# └── sidebars.js                                     # 侧边栏配置

配置文件¶

// docusaurus.config.js
/** @type {import('@docusaurus/types').Config} */
const config = {
  title: '我的项目',                                    // 网站标题
  tagline: '一个很棒的项目',                              // 副标题
  url: 'https://example.com',                          // 网站地址
  baseUrl: '/',                                        // 基础路径

  // 主题配置
  themeConfig: {
    navbar: {                                          // 顶部导航栏
      title: '我的项目',
      items: [
        { type: 'doc', docId: 'intro', label: '文档' }, // 文档链接
        { to: '/blog', label: '博客' },                 // 博客链接
        { href: 'https://github.com/...', label: 'GitHub' },
      ],
    },
    footer: {                                          // 底部
      style: 'dark',
      copyright: `Copyright © ${new Date().getFullYear()}`,
    },
    colorMode: {                                       // 明暗模式
      defaultMode: 'light',
      respectPrefersColorScheme: true,                 // 跟随系统
    },
  },

  // 预设（包含文档+博客+页面插件）
  presets: [
    ['classic', {
      docs: {
        sidebarPath: './sidebars.js',                  // 侧边栏配置
        editUrl: 'https://github.com/.../edit/main/',  // 编辑链接
      },
      blog: { showReadingTime: true },                 // 显示阅读时间
      theme: { customCss: './src/css/custom.css' },    // 自定义样式
    }],
  ],
};

module.exports = config;

写文档¶

---
sidebar_position: 1
title: 快速开始
description: 5分钟上手指南
tags: [入门, 教程]
---

# 快速开始

这是文档内容，支持标准 Markdown。

## 使用 MDX 嵌入 React 组件

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm">

  ```bash
  npm install my-package
  ```

  </TabItem>
  <TabItem value="yarn" label="yarn">

  ```bash
  yarn add my-package
  ```

  </TabItem>
</Tabs>

:::tip 小技巧
这是一个提示框，Docusaurus 内置支持。
:::

:::warning 注意
这是一个警告框。
:::

:::danger 危险
这是一个危险警告。
:::

版本管理¶

# 创建新版本快照
npm run docusaurus docs:version 1.0                    # 为当前文档创建 v1.0 快照

# 文件结构变化
# versioned_docs/
# └── version-1.0/                                    # v1.0 文档快照
# versioned_sidebars/
# └── version-1.0-sidebars.json                       # v1.0 侧边栏
# versions.json                                       # 版本列表

# docs/ 目录始终是 "下一版"（开发中）

构建部署¶

npm run build                                         # 构建静态网站（输出到 build/）
npm run serve                                         # 本地预览构建结果

# 部署到 GitHub Pages
USE_SSH=true npm run deploy                            # SSH 方式部署
GIT_USER=<username> npm run deploy                     # HTTPS 方式部署

常见报错¶

报错	原因	解决
`Module not found`	缺少依赖	`npm install` 重新安装
`MDX compilation error`	MDX 语法错误	检查 JSX 标签是否闭合
`Broken link`	文档链接失效	检查链接路径，运行 `npm run build` 会报告
`Sidebar item not found`	侧边栏引用了不存在的文档	检查 `sidebars.js` 配置
`Node.js version`	Node 版本太低	升级到 Node >= 18

速查表¶

# 项目管理
npx create-docusaurus@latest <name> classic           # 创建项目
npm start                                             # 开发预览
npm run build                                         # 构建
npm run deploy                                        # 部署

# 文档管理
npm run docusaurus docs:version <ver>                  # 创建版本

# Markdown 增强
# :::tip / :::warning / :::danger / :::info           # 提示框
# <Tabs> + <TabItem>                                  # 标签页
# import Component from '@theme/...'                  # 引入组件

# 适用场景
# React 项目文档 → Docusaurus
# Vue 项目文档 → VitePress
# Python 项目文档 → MkDocs / Sphinx