---
title: docusaurus构建说明
sidebar_position: 1
---


## Docusaurus 项目结构
### 搭建流程

```
1.初始化
npx create-docusaurus@latest my-website classic

2.启动
npm start

# 附
好看的网站  https://ai-speaker.com/
```
### 修改内容
```
# 配置
1.blog的预计阅读时间关,默认展示数量改成无限
2.i18默认zh-Hans
3.colorMode默认浅色,不使用用户偏好色

# 样式
1.表格样式
2.代码块字体样式,java代码识别

# 其他
1.editUrl 可以在本地打开typora
1.1先搞个注册表register-typora-protocol.reg 目标路径 typora-handler.wsf
1.2再wsf转换一下url编码,然后静默打开typora
2.新增了启动器start.vbs
```

### 增加一个docs页

```
# docusaurus.config.ts
 plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        path: 'docs2',
        routeBasePath: 'docs2',
        sidebarPath: './sidebars.ts',
        editUrl: 'typora://file/D:/projects/my-website/',
      },
    ],
  ],


themeConfig.navbar.items:
{
  type: 'docSidebar',
  sidebarId: 'tutorialSidebar2',
  docsPluginId: 'docs2',
  position: 'left',
  label: '文档2',
},

# sidebars.ts
tutorialSidebar2: [{type: 'autogenerated', dirName: '.'}],
```



## 一端多git-ssh

```
#生成ssh秘钥
ssh-keygen -t ed25519 -C "haotiandev@outlook.com" -f ~/.ssh/id_ed25519_gitee

#私钥 C:\Users\haoti\.ssh\id_ed25519_gitee

#找到公钥 C:\Users\haoti\.ssh\id_ed25519_gitee.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ5usext5BEGqdXEkwIgdOWZodGCMZqlOpMs7pmYuO3V haotiandev@outlook.com

#把公钥在git后台配进ssh公钥里

#在C:\Users\haoti\.ssh 下创建config文件,写入
# 个人 Gitee 账号
Host gitee.com
HostName gitee.com
User git
IdentityFile ~/.ssh/id_ed25519_gitee
IdentitiesOnly yes

#绑定git地址
git remote add origin git@gitee.com:lhth/docusaurus.git

#测试
ssh -T git@gitee.com
```



## 完整项目地图

```
my-website/
│
├── 📄 docusaurus.config.js    ← 【核心】整个站点的总配置
│                                 标题、导航栏、页脚、主题、插件、国际化、深色模式……一切全局设置
├── 📄 sidebars.js             ← 文档侧边栏菜单的结构定义
├── 📄 package.json            ← 项目依赖 + npm 启动脚本
│
├── 📁 blog/                   ← 博客系统
│   ├── authors.yml            ← 作者信息（头像、简介、社交链接）
│   ├── tags.yml               ← 博客标签定义
│   ├── 2021-08-26-welcome/    ← 博客可以是文件夹（含图片等资源）
│   ├── 2019-05-28-first-blog-post.mdx    ← 单文件博客文章
│   ├── 2019-05-29-long-blog-post.mdx     ← 文件名格式：YYYY-MM-DD-标题.mdx
│   └── 2021-08-01-mdx-blog-post.mdx      ← 用 Markdown + JSX 写作
│       ↑ 自动生成：RSS 订阅、标签筛选页、文章归档页
│
├── 📁 docs/                   ← 文档系统
│   ├── intro.mdx              ← 文档的首页 / 入口
│   ├── tutorial-basics/       ← 一个文档章节（目录）
│   │   ├── _category_.json    ← 章节配置：标签名、排序、是否折叠
│   │   ├── congratulations.mdx
│   │   ├── create-a-blog-post.mdx
│   │   ├── create-a-document.mdx
│   │   ├── create-a-page.mdx
│   │   ├── deploy-your-site.mdx
│   │   └── markdown-features.mdx
│   └── tutorial-extras/       ← 另一个章节
│       ├── _category_.json
│       ├── manage-docs-versions.mdx
│       ├── translate-your-site.mdx
│       └── img/               ← 文档里引用的图片
│       ↑ 支持多版本管理（v1, v2, next……）
│
├── 📁 src/                    ← 自定义代码（React）
│   ├── pages/                 ← 独立页面，文件会自动生成路由
│   │   ├── index.js           ← 【首页！】网站的主入口页
│   │   ├── index.module.css   ← 首页专属样式
│   │   └── markdown-page.mdx  ← 纯 Markdown 写页面
│   ├── components/            ← 可复用的 React 组件
│   │   └── HomepageFeatures/  ← 首页的"特性展示"区块组件
│   └── css/
│       └── custom.css         ← 全局自定义样式（覆盖主题默认样式）
│
├── 📁 static/                 ← 静态资源（原封不动复制到最终网站根目录）
│   ├── img/
│   │   ├── favicon.ico        ← 浏览器标签页小图标
│   │   ├── logo.svg           ← 导航栏 Logo
│   │   ├── docusaurus-social-card.jpg  ← 分享到社交媒体时的预览图
│   │   ├── docusaurus.png
│   │   └── undraw_docusaurus_*.svg  ← 首页的插画素材
│   └── .nojekyll              ← GitHub Pages 需要（告诉 GitHub 这不是 Jekyll 项目）
│
├── 📁 .docusaurus/            ← 【自动生成】Docusaurus 内部缓存和构建产物
│   │                           ← 千万不要手动编辑！里面有个文件叫
│   │                              DONT-EDIT-THIS-FOLDER 就在提醒这一点
│   │                           ← 可以随时删掉（npm run clear），
│   │                              下次 npm start / build 会自动重建
│   │
│   ├── docusaurus.config.mjs  ← 源配置编译后的版本
│   ├── routes.js / routesChunkNames.json  ← 站点路由表（代码分割用）
│   ├── registry.js            ← 所有页面和组件的模块注册表
│   ├── globalData.json        ← 各插件暴露的全局运行时数据
│   ├── i18n.json              ← 国际化翻译数据
│   ├── site-metadata.json     ← 站点元信息
│   ├── site-storage.json      ← 持久化存储
│   ├── client-modules.js      ← 客户端模块入口
│   │
│   ├── docusaurus-plugin-content-docs/  ← 文档插件缓存
│   │   ├── default/
│   │   │   └── p/             ← 每个 .mdx 文档文件被编译成一个 JSON
│   │   │       ↑ 浏览器最终加载的就是这些 JSON
│   │   │
│   ├── docusaurus-plugin-content-blog/  ← 博客插件缓存
│   │   └── default/
│   │       ├── blogMetadata-default.json  ← 博客元数据
│   │       ├── blog-post-list-prop-default.json
│   │       └── p/             ← 博客文章、标签页、归档页的编译产物
│   │
│   ├── docusaurus-plugin-content-pages/ ← 独立页面插件缓存
│   ├── docusaurus-plugin-css-cascade-layers/  ← CSS 层级管理
│   └── docusaurus-plugin-debug/        ← 调试页面
│
├── 📁 node_modules/           ← npm 安装的依赖包，不用关心里面
│
├── 📄 README.md               ← GitHub 项目首页显示的说明
├── 📄 README_tome.md          ← 就是你现在看的这份笔记
└── 📄 .gitignore              ← Git 忽略规则
```

---

## 各目录一句话速查

| 目录 / 文件 | 一句话 |
|---|---|
| `docusaurus.config.js` | 站点的全部配置，修改标题、导航、主题都在这 |
| `sidebars.js` | 文档侧边栏菜单怎么排 |
| `blog/` | 写博客，Markdown → 自动生成文章页 + RSS + 标签 |
| `docs/` | 写文档，Markdown → 自动生成带侧边栏的文档站 |
| `src/pages/` | 自己写 React 页面（首页就在这） |
| `src/components/` | 自己写 React 组件 |
| `src/css/custom.css` | 覆盖主题样式（改颜色、字体等） |
| `static/` | 放图片、favicon 等不需要构建的文件 |
| `.docusaurus/` | 内部缓存，别动，出问题就删掉重来 |
| `node_modules/` | 第三方依赖 |

---

## 常用命令

| 命令 | 用途 |
|---|---|
| `npm start` | 启动开发服务器，自动打开浏览器，支持热更新 |
| `npm run build` | 生成生产环境静态文件到 `build/` 目录 |
| `npm run serve` | 本地预览构建后的产物 |
| `npm run clear` | 删除 `.docusaurus/` 缓存（出问题先试试这个） |
| `npm run deploy` | 部署到 GitHub Pages（需额外配置） |

---

## 数据流概览（简化版）

```
你写的 Markdown（docs/ + blog/）
        ↓ Docusaurus 编译
  .docusaurus/ 里面的 JSON
        ↓ 浏览器加载
    网站页面渲染
```

- MDX = Markdown + JSX（可以在 Markdown 里直接写 React 组件）
- 所有页面最终都是 React 组件，但大多数情况下你只需要写 Markdown