Docusaurus 使用指南

从项目结构到日常使用，全面了解 Docusaurus 的使用方式。

项目结构

初始化后的目录结构如下：

docs-site/
├── blog/                    # 博客文章目录
│   ├── authors.yml          # 作者信息
│   ├── tags.yml             # 标签定义
│   └── 2026-05-22-post/     # 每篇博客一个文件夹
│       └── index.mdx
├── docs/                    # 文档目录
│   └── intro.mdx
├── src/
│   ├── css/
│   │   └── custom.css       # 全局自定义样式
│   └── pages/
│       ├── index.tsx         # 首页组件
│       └── index.module.css  # 首页样式
├── static/
│   └── img/                 # 静态资源（图片、favicon 等）
├── docusaurus.config.ts     # 核心配置文件
├── sidebars.ts              # 侧边栏配置
└── package.json

配置文件

docusaurus.config.ts 是站点的核心配置，以下为关键字段说明：

站点基本信息

const config: Config = {
  title: '站点名称',           // 浏览器标题栏和导航栏显示的名称
  tagline: '站点副标题',        // 首页标语
  favicon: 'img/favicon.svg',  // 浏览器标签页图标

  url: 'https://xxx.github.io', // 生产环境地址
  baseUrl: '/',                 // 本地用 /；GitHub Pages 用 /仓库名/

  organizationName: 'github用户名',
  projectName: '仓库名',
};

国际化

i18n: {
  defaultLocale: 'zh-Hans',   // 默认语言
  locales: ['zh-Hans'],       // 支持的语言列表
},

文档和博客配置

presets: [
  [
    'classic',
    {
      docs: {
        sidebarPath: './sidebars.ts',   // 侧边栏文件路径
        editUrl: 'https://github.com/xxx/xxx/tree/main/',
      },
      blog: {
        showReadingTime: true,           // 显示阅读时间
        feedOptions: {                   // RSS 订阅
          type: ['rss', 'atom'],
          xslt: true,
        },
      },
      theme: {
        customCss: './src/css/custom.css',
      },
    },
  ],
],

导航栏

navbar: {
  title: '站点名',
  logo: { alt: 'Logo', src: 'img/logo.svg' },
  items: [
    {
      type: 'docSidebar',        // 文档侧边栏链接
      sidebarId: 'tutorialSidebar',
      position: 'left',
      label: '文档',
    },
    { to: '/blog', label: '博客', position: 'left' },
    {
      href: 'https://github.com/...',
      label: 'GitHub',
      position: 'right',
    },
  ],
},

页脚

footer: {
  style: 'dark',
  links: [
    {
      title: '分类标题',
      items: [
        { label: '链接文字', to: '/docs/intro' },
        { label: '外部链接', href: 'https://...' },
      ],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} Built with Docusaurus.`,
},

主题模式

colorMode: {
  defaultMode: 'light',              // 默认主题：light | dark
  respectPrefersColorScheme: true,   // 是否跟随系统偏好
},

添加文档

创建文档

在 docs/ 目录下创建 .md 或 .mdx 文件：

---
sidebar_position: 1    # 在侧边栏中的排序位置
---

# 文档标题

文档内容使用 Markdown 编写。

Front Matter 字段

字段	说明
sidebar_position	侧边栏排序（数字越大越靠后）
sidebar_label	侧边栏显示的文字（默认取标题）
title	页面标题
description	页面描述（SEO）
toc_max_heading_level	目录最大标题级别
pagination_prev	自定义上一页链接
pagination_next	自定义下一页链接

MDX 扩展能力

.mdx 文件支持嵌入 React 组件：

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

<Tabs>
  <TabItem value="js" label="JavaScript">
    ```js
    console.log('hello');
    ```
  </TabItem>
  <TabItem value="py" label="Python">
    ```python
    print('hello')
    ```
  </TabItem>
</Tabs>

常用的内置组件：

• Tabs / TabItem — 标签页切换
• Admonition — 提示框（info/warning/danger/tip）
• Details — 折叠内容

文档间链接

# 相对路径链接
[另一篇文档](./other-doc)

# 绝对路径链接（相对于 docs/ 目录）
[部署指南](/docs/deploy-docusaurus)

# 引用图片
![描述](./images/screenshot.png)

添加博客

创建博客

在 blog/ 下创建 YYYY-MM-DD-slug/index.mdx：

---
slug: custom-slug          # 自定义 URL 路径（可选）
title: 博客标题
authors: pomili            # 对应 authors.yml 中的 key
tags: [标签1, 标签2]
---

博客内容...

{/* truncate */}           # 截断标记，之前的内容显示在列表页

日期规则

• 文件名必须以 YYYY-MM-DD- 开头
• 日期决定博客的显示顺序
• 可设置未来日期来定时发布

作者配置

在 blog/authors.yml 中定义作者：

pomili:
  name: pomili
  title: 开发者
  page: true                        # 是否为作者生成独立页面
  socials:
    github: pomili

标签配置

在 blog/tags.yml 中定义标签：

docusaurus:
  label: Docusaurus
  permalink: /docusaurus            # 标签页 URL
  description: Docusaurus 相关文章

图片引用

博客中的图片建议放在与 index.mdx 同级目录：

blog/2026-05-22-my-post/
├── index.mdx
└── screenshot.png

![截图](./screenshot.png)

侧边栏配置

sidebars.ts 控制文档的侧边栏结构：

自动生成

根据 docs/ 目录结构自动生成：

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

手动配置

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',                         // 对应 docs/intro.mdx
    'docusaurus-guide',
    {
      type: 'category',
      label: '教程',
      collapsible: true,             // 是否可折叠
      collapsed: false,              // 默认是否折叠
      items: [
        'tutorial/part1',
        'tutorial/part2',
      ],
    },
    {
      type: 'link',                  // 外部链接
      label: 'Docusaurus 官网',
      href: 'https://docusaurus.io/',
    },
  ],
};

自定义样式

src/css/custom.css 通过覆盖 CSS 变量来实现主题定制：

:root {
  --ifm-color-primary: #2da44e;          /* 主色调 */
  --ifm-font-family-base: system-ui;     /* 基础字体 */
  --ifm-background-color: #ffffff;       /* 页面背景 */
  --ifm-navbar-background-color: #f6f8fa; /* 导航栏背景 */
}

/* 暗色模式 */
[data-theme='dark'] {
  --ifm-color-primary: #3fb950;
  --ifm-background-color: #0d1117;
}

首页定制

首页位于 src/pages/index.tsx，可以完全自定义。配套的 CSS 写在 src/pages/index.module.css：

import Layout from '@theme/Layout';

export default function Home() {
  return (
    <Layout title="首页" description="站点描述">
      <div>{/* 你的首页内容 */}</div>
    </Layout>
  );
}

本地开发

# 启动开发服务器（热更新）
npm start

# 构建生产版本
npm run build

# 本地预览构建结果
npm run serve

部署到 GitHub Pages

使用 GitHub Actions 自动部署，在 .github/workflows/deploy.yml 中配置：

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

关键注意点：

• GitHub Pages 部署时 baseUrl 需设为 /<仓库名>/
• 仓库 Settings → Pages 中选择 gh-pages 分支作为部署源
• 确保 workflow 有 contents: write 权限

常见组件

提示框

:::tip 提示
这是一个有用的提示。
:::

:::info 信息
这是一条补充信息。
:::

:::warning 注意
这是一条警告。
:::

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

代码块

```python title="hello.py" {2,4-5} showLineNumbers
def greet(name):
    # 高亮第 2 行和第 4-5 行
    message = f"Hello, {name}!"
    print(message)

greet("World")
```

折叠内容

<details>
  <summary>点击展开</summary>

隐藏的内容写在这里。

</details>

---

掌握了以上内容，就可以顺畅地使用 Docusaurus 来维护文档和博客了。更多细节可查阅 Docusaurus 官方文档。