跳到主要内容

Docusaurus 完整教程（新手向）

阅读需 7 分钟

本教程面向零基础或刚接触 Docusaurus 的开发者，按由浅入深的顺序讲解所有主要知识点。建议按章节顺序阅读。

一、Docusaurus 简介​

什么是 Docusaurus？​

Docusaurus 是 Meta（Facebook）开源 的静态站点生成器，专门为 文档站、博客、产品主页 设计。特点包括：

  • 基于 React：可嵌入 React 组件，扩展性强
  • Markdown / MDX 优先：用熟悉的 Markdown 写文档，支持 JSX
  • 开箱即用：侧边栏、导航、搜索、深色模式、多语言等内置
  • 静态站点：构建后是纯 HTML/CSS/JS，易部署、速度快

适合做什么？​

  • 产品/API 文档
  • 技术博客
  • 开源项目说明站
  • 团队知识库

二、环境准备与创建项目​

环境要求​

  • Node.js：建议 20.0 及以上（LTS 即可）
  • 包管理器：npm / yarn / pnpm 任选其一

创建新项目​

使用官方脚手架（经典模板）：

npm init docusaurus@latest my-website classic

按提示选择：

  • 模板：classic（包含文档 + 博客）
  • 是否使用 TypeScript：按需选择

进入项目并启动开发服务器：

cd my-website
npm run start

在浏览器打开 http://localhost:3000 即可看到默认站点。

WSL / 远程开发

若在 WSL 中运行、用 Windows 浏览器访问，需让开发服务器监听所有网卡。在 package.json 中把启动脚本改为：

"start": "docusaurus start --host 0.0.0.0"

然后可用 WSL 的 IP 访问，如 http://172.x.x.x:3000。

三、项目目录结构​

理解目录结构有助于后续自定义和排查问题。

my-website/
├── blog/                 # 博客文章（按日期或文件夹组织）
├── docs/                 # 文档源文件（Markdown/MDX）
├── src/
│   ├── components/       # 自定义 React 组件
│   ├── css/              # 全局样式（如 custom.css）
│   └── pages/            # 独立页面，对应站点路由
├── static/               # 静态资源（图片、favicon 等），会原样复制到站点根目录
├── docusaurus.config.ts  # 站点主配置
├── sidebars.ts           # 文档侧边栏配置
└── package.json

重点目录说明：

目录/文件作用
docs/所有「文档」类页面，自动参与侧边栏与导航
blog/博客文章，自动按时间列表与归档
src/pages/自定义页面，每个文件对应一个路由（如 about.js → /about）
static/放图片、PDF 等，引用时路径从根写起，如 /img/logo.png
docusaurus.config.ts站点标题、URL、主题、插件、导航栏、页脚等
sidebars.ts文档侧边栏顺序与分组

四、编写文档（docs）​

4.1 新建一篇文档​

在 docs/ 下新建任意 .md 或 .mdx 文件即可，例如：

# 例如
docs/quick-start.md
docs/guide/install.md

文件顶部可写 Front Matter（YAML），用于配置当前页在侧边栏和 SEO 等行为。

4.2 Front Matter 常用字段​

---
# 侧边栏显示的文字（默认用标题）
sidebar_label: 快速开始
# 侧边栏中的排序，数字越小越靠前
sidebar_position: 1
# 页面标题（浏览器标签、SEO）
title: 快速开始
# 页面描述（SEO）
description: 5 分钟上手 Docusaurus
# 自定义 URL 最后一段，默认用文件名
slug: /quick-start
# 是否在侧边栏中隐藏
sidebar_class_name: 可选 CSS 类名
---

示例：

docs/quick-start.mdmd
---
sidebar_label: 快速开始
sidebar_position: 1
title: 快速开始
---

# 快速开始

这里是正文……

保存后，开发服务器会热更新，文档会出现在侧边栏并可按 sidebar_position 排序。

4.3 文档之间的链接​

  • 站内文档：用 Markdown 链接到相对路径或绝对路径均可。
[安装说明](./install)
[介绍](/docs/intro)
  • 推荐：使用 Docusaurus 的「文档链接」语法，便于以后改 path 时统一替换：
[介绍](intro.md)

五、侧边栏（Sidebar）配置​

5.1 自动生成（默认）​

在 sidebars.ts 中常见写法：

const sidebars: SidebarsConfig = {
  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
};

表示根据 docs/ 的目录和文件名自动生成侧边栏，顺序由各文档的 sidebar_position 和文件名共同决定。

5.2 用文件夹分组（分类）​

在 docs/ 下建子文件夹，并在该文件夹内放一个 _category_.json 即可成为一个「分类」：

// docs/guide/_category_.json
{
  "label": "使用指南",
  "position": 2,
  "link": {
    "type": "generated-index",
    "title": "指南索引",
    "description": "按主题查阅使用说明。"
  }
}
  • label：侧边栏中显示的分类名
  • position：分类在侧边栏中的顺序
  • link：可选，点分类名时进入「索引页」

5.3 手动配置侧边栏​

若需要完全自定义顺序和结构，可在 sidebars.ts 中手写：

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',
    'quick-start',
    {
      type: 'category',
      label: '使用指南',
      items: ['guide/install', 'guide/usage'],
    },
  ],
};
  • 字符串：对应 docs/ 下的文档 ID（通常为不含扩展名的路径）
  • type: 'category'：分组，items 为子文档列表

六、Markdown 与 MDX​

6.1 支持的 Markdown 语法​

Docusaurus 使用 MDX（Markdown + JSX），所以普通 Markdown 都支持，例如：

  • 标题、列表、引用、表格
  • 粗体、斜体、代码
  • 链接、图片
  • 代码块（带语法高亮）

代码块可指定语言和标题：

```js title="utils.js"
export function add(a, b) {
  return a + b;
}
```

6.2 使用 Admonition（提示框）​

内置的「提示框」组件，适合做说明、注意、警告等：

:::note[说明]
这是一段说明文字。
:::

:::tip[提示]
小技巧。
:::

:::danger[注意]
谨慎操作。
:::

:::info[信息]
补充信息。
:::

:::caution[警告]
可能带来的风险。
:::

6.3 在 MDX 中使用 React 组件​

文件扩展名改为 .mdx 后，可直接写 JSX：

import MyComponent from '@site/src/components/MyComponent';

## 章节标题

普通 Markdown 内容……

<MyComponent name="Docusaurus" />

可引入 src/components/ 下的自定义组件，或 Docusaurus 内置组件（如 TOCInline、CodeBlock 等）。

6.4 在 Markdown 中插入 JSX（不换 .mdx）​

若保持 .md 扩展名，仍可使用部分「类似 HTML」的写法，但复杂组件建议用 .mdx 并 import。

七、博客（Blog）​

7.1 文章放在哪​

  • 方式一：直接在 blog/ 下放 YYYY-MM-DD-标题.md
  • 方式二：在 blog/ 下建子文件夹，如 blog/2024/03/15-hello.md

文件名中的日期会用于排序和 URL。

7.2 博客 Front Matter​

---
slug: my-first-post
title: 我的第一篇文章
authors: [slorber]
tags: [hello, docusaurus]
date: 2024-03-15
---

正文……
  • authors：对应 blog/authors.yml 中定义的作者 ID
  • tags：标签，可在 blog/tags.yml 中定义
  • date：发布日期

7.3 关闭或自定义博客​

在 docusaurus.config.ts 的 preset 中可关闭博客或改路径：

presets: [
  [
    'classic',
    {
      blog: {
        path: 'news',        // 博客路径改为 /news
        showReadingTime: true,
        blogTitle: '动态',
      },
    },
  ],
],

八、自定义页面（src/pages）​

8.1 约定式路由​

src/pages/ 下的文件会变成站点路由：

  • src/pages/index.js → /
  • src/pages/about.js → /about
  • src/pages/help/index.js → /help

8.2 页面写法​

可以是 React 函数组件，导出默认组件即可：

// src/pages/about.js
import React from 'react';
import Layout from '@theme/Layout';

export default function About() {
  return (
    <Layout title="关于" description="关于本站">
      <main>
        <h1>关于我们</h1>
        <p>这里是关于页内容。</p>
      </main>
    </Layout>
  );
}

使用 <Layout> 可保持与全站一致的导航栏、侧边栏和页脚。

8.3 覆盖首页​

若想完全自定义首页，可修改或替换 src/pages/index.js，或通过 docusaurus.config.ts 的 plugins 配置首页路由。

九、导航栏与页脚​

9.1 导航栏（navbar）​

在 docusaurus.config.ts 的 themeConfig.navbar 中配置：

themeConfig: {
  navbar: {
    title: '我的站点',
    logo: {
      alt: 'Logo',
      src: 'img/logo.svg',
    },
    items: [
      { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: '文档', position: 'left' },
      { to: '/blog', label: '博客', position: 'left' },
      { type: 'docsVersionDropdown', position: 'right' },
      { type: 'localeDropdown', position: 'right' },
      { href: 'https://github.com/xxx', label: 'GitHub', position: 'right' },
    ],
  },
},
  • docSidebar：指向某个侧边栏（文档入口）
  • to：站内路径
  • href：站外链接
  • docsVersionDropdown / localeDropdown：版本、语言下拉（需先启用对应功能）

9.2 页脚（footer）​

在 themeConfig.footer 中配置链接和版权信息，结构与 navbar 类似，可设多列链接和 copyright 文案。

十、主题与样式​

10.1 全局样式​

在 src/css/custom.css 中写全局 CSS，会作用于全站。例如修改主题色、字体等：

:root {
  --ifm-color-primary: #2e8555;
  --ifm-font-family-base: 'Your Font', system-ui, sans-serif;
}

10.2 深色模式​

默认支持跟随系统或手动切换。在 themeConfig.colorMode 中可配置：

colorMode: {
  defaultMode: 'light',
  respectPrefersColorScheme: true,
},

10.3 自定义组件样式​

  • 给某页或某组件包一层带 class 的 div，在 custom.css 中用该类名写样式
  • 或使用 Swizzle 复制主题组件到项目中再改：npm run swizzle @docusaurus/theme-classic NavbarItem --eject（按需使用）

十一、配置文件（docusaurus.config）​

11.1 核心字段​

字段说明
title站点标题
url站点最终访问的根 URL（部署后要改）
baseUrl子路径，如 GitHub Pages 用 '/projectName/'
faviconfavicon 路径
organizationName / projectName常用于 GitHub 部署与编辑链接
presets预设（如 classic），以及 docs/blog 等开关与选项
themeConfig导航栏、页脚、颜色、Algolia 搜索等
plugins插件列表
i18n多语言配置

11.2 多语言（i18n）​

i18n: {
  defaultLocale: 'zh-Hans',
  locales: ['zh-Hans', 'en'],
},

然后在项目根执行：

npm run write-translations

会在 i18n/ 下生成待翻译的 JSON，翻译后构建时会生成各语言版本。

11.3 文档版本（Versioning）​

适用于「多个大版本文档并存」的场景。首次为当前内容打一个版本：

npm run docusaurus docs:version 1.0

会生成 versioned_docs/version-1.0/ 等，并在导航栏出现版本选择器。新文档继续在 docs/ 写，代表「当前/下一版」。

十二、构建与部署​

12.1 本地构建​

npm run build

产物在 build/ 目录，为静态 HTML/CSS/JS。

12.2 本地预览构建结果​

npm run serve

会以生产模式打开 build/ 内容，用于检查部署效果。

12.3 部署到 GitHub Pages​

  • 安装 gh-pages：npm install --save-dev gh-pages
  • 在 package.json 中加：
"scripts": {
  "deploy": "docusaurus deploy"
}
  • 在 docusaurus.config.ts 中设置：
url: 'https://你的用户名.github.io',
baseUrl: '/仓库名/',
projectName: '仓库名',
organizationName: '你的用户名',
  • 执行：npm run deploy（会构建并推送到 gh-pages 分支）

12.4 部署到其他平台​

只要能把 build/ 目录的内容放到任意静态托管即可（Vercel、Netlify、自有 Nginx 等）。构建命令为 npm run build，站点根目录指向 build。

十三、常用命令速查​

命令说明
npm run start启动开发服务器（可加 --host 0.0.0.0）
npm run build生产环境构建
npm run serve本地预览构建结果
npm run deploy构建并部署（如 GitHub Pages）
npm run clear清除缓存与构建产物
npm run swizzle <组件>将主题组件「拷贝」到项目以便覆盖
npm run write-translations生成多语言翻译文件
npm run docusaurus docs:version <版本号>为文档打版本

十四、学习路径小结​

  1. 入门：创建项目 → 改 docs/intro.md → 看侧边栏与热更新
  2. 文档：在 docs/ 新增文档、用 Front Matter 和 _category_.json 组织侧边栏
  3. 内容：掌握 MDX、代码块、Admonition、自定义组件
  4. 博客：在 blog/ 写文章，配置 authors/tags
  5. 页面：在 src/pages/ 做关于页、落地页等
  6. 外观：改 custom.css、navbar、footer
  7. 配置：熟悉 docusaurus.config.ts 与 sidebars.ts
  8. 进阶：i18n、版本、Swizzle、自定义插件

遇到问题可查阅 Docusaurus 官方文档。

Loading Comments...