mzb.github.io 项目分析

一、项目概述

本项目是一个基于 Docusaurus v3.9.2 构建的静态文档/博客网站。Docusaurus 是由 Facebook（Meta）开发的现代化静态站点生成器，专为文档类网站设计。

当前项目使用的是 Docusaurus 默认模板，包含示例教程文档和博客文章，可作为个人文档站、技术博客或项目主页的基础进行定制开发。

主要功能：

• 文档管理系统（支持 Markdown/MDX 编写，自动生成侧边栏导航）
• 博客系统（支持作者管理、标签分类、RSS 订阅）
• 自定义页面（基于 React 组件开发）
• 内置搜索、暗色模式、响应式布局
• 静态站点生成，便于部署到任意托管平台

---

二、框架与模块关系

核心框架

Docusaurus v3.9.2（Classic Preset）— 基于 React 的静态站点生成器

项目目录结构

mzb.github.io/
├── docusaurus.config.ts    # 核心配置文件（站点名称、URL、导航栏、页脚、插件、主题等）
├── sidebars.ts             # 文档侧边栏配置（默认从 docs/ 目录自动生成）
├── tsconfig.json           # TypeScript 配置
├── package.json            # 项目依赖与脚本命令
│
├── src/                    # 源代码目录
│   ├── pages/              # 自定义页面
│   │   ├── index.tsx       #   └─ 首页（Hero Banner + 特性展示）
│   │   ├── index.module.css#   └─ 首页样式
│   │   └── markdown-page.md#   └─ 示例 Markdown 页面
│   ├── components/         # 可复用 React 组件
│   │   └── HomepageFeatures/
│   │       ├── index.tsx   #   └─ 首页特性卡片组件
│   │       └── styles.module.css
│   └── css/                # 全局样式
│       └── custom.css      #   └─ 主题变量与自定义样式
│
├── docs/                   # 文档内容（Markdown）
│   ├── intro.md            #   └─ 教程入门
│   ├── tutorial-basics/    #   └─ 基础教程（5 篇）
│   └── tutorial-extras/    #   └─ 进阶教程（2 篇）
│
├── blog/                   # 博客内容（Markdown/MDX）
│   ├── authors.yml         #   └─ 作者信息配置
│   ├── tags.yml            #   └─ 标签配置
│   └── *.md / *.mdx        #   └─ 博客文章
│
├── static/                 # 静态资源
│   └── img/                #   └─ 图片、图标、Logo 等
│
└── build/                  # 构建输出目录（运行 build 后生成）

模块关系图

┌─────────────────────────────────────────────────────┐
│              docusaurus.config.ts                     │
│         （全局配置中心：站点信息、导航、主题）           │
└──────────┬───────────────┬──────────────┬────────────┘
           │               │              │
     ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
     │  src/pages │  │   docs/   │  │   blog/   │
     │ (自定义页面)│  │ (文档内容) │  │ (博客内容) │
     └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
           │               │              │
     ┌─────▼──────────┐   │              │
     │ src/components/ │   │              │
     │  (React 组件)   │   │              │
     └─────┬──────────┘   │              │
           │               │              │
     ┌─────▼─────┐  ┌─────▼─────┐       │
     │  src/css/  │  │ sidebars  │       │
     │ (主题样式)  │  │.ts(侧边栏)│       │
     └───────────┘  └───────────┘       │
           │               │              │
           └───────────────┼──────────────┘
                           ▼
                  ┌─────────────────┐
                  │  static/ 静态资源 │
                  │ （图片、图标等）   │
                  └────────┬────────┘
                           ▼
                  ┌─────────────────┐
                  │   build/ 输出    │
                  │ （静态 HTML/CSS/JS）│
                  └─────────────────┘

---

三、技术栈

类别	技术	版本
站点框架	Docusaurus	3.9.2
UI 框架	React	19.0.0
编程语言	TypeScript	5.6.2
内容格式	Markdown / MDX	MDX 3.0.0
CSS 框架	Infima（Docusaurus 内置）	-
代码高亮	Prism React Renderer	2.3.0
工具库	clsx（CSS 类名拼接）	2.0.0
运行环境	Node.js	>= 20.0
包管理器	npm	-

---

四、发布到自己网页的步骤

方式一：GitHub Pages（推荐，免费）

第 1 步：修改配置文件

编辑 docusaurus.config.ts，将以下占位内容替换为你的实际信息：

const config: Config = {
  title: '你的网站名称',
  tagline: '你的网站描述',
  url: 'https://mzb.github.io',           // 你的 GitHub Pages URL
  baseUrl: '/',                            // 用户名.github.io 仓库，baseUrl 为 '/'
  organizationName: 'mzb',
  projectName: 'mzb.github.io',
  // ...
};

第 2 步：初始化 Git 并推送到 GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/你的用户名/mzb.github.io.git
git push -u origin main

第 3 步：部署到 GitHub Pages

# 方式 A：使用 SSH
USE_SSH=true npm run deploy

# 方式 B：使用 HTTPS
GIT_USER=你的GitHub用户名 npm run deploy

部署完成后，访问 https://mzb.github.io/ 即可看到网站。

---

方式二：Vercel（推荐，操作简单）

1. 将项目推送到 GitHub 仓库
2. 访问 vercel.com，使用 GitHub 账号登录
3. 点击 "Import Project"，选择你的仓库
4. Vercel 会自动识别 Docusaurus 项目，直接点击 "Deploy"
5. 部署完成后会获得一个 xxx.vercel.app 的域名，也可绑定自定义域名

---

方式三：Netlify

1. 将项目推送到 GitHub 仓库
2. 访问 netlify.com，使用 GitHub 账号登录
3. 点击 "New site from Git"，选择你的仓库
4. 构建设置：
   • Build command: npm run build
   • Publish directory: build
5. 点击 "Deploy site"

---

方式四：手动部署到自有服务器

第 1 步：本地构建

npm run build

第 2 步：上传 build 目录

将 build/ 目录下的所有文件上传到你的服务器（通过 FTP、SCP、rsync 等方式）。

第 3 步：配置 Web 服务器

Nginx 配置示例：

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/mzb.github.io;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

---

五、常用命令速查

命令	说明
npm start	启动本地开发服务器（热更新，默认端口 3000）
npm run build	构建生产环境静态文件到 build/ 目录
npm run serve	本地预览构建后的网站
npm run deploy	部署到 GitHub Pages
npm run typecheck	TypeScript 类型检查
npm run clear	清除 Docusaurus 缓存

---

六、快速上手建议

1. 自定义网站信息：编辑 docusaurus.config.ts 修改网站名称、描述、导航栏、页脚等
2. 编写文档：在 docs/ 目录下添加 Markdown 文件，侧边栏会自动更新
3. 发布博客：在 blog/ 目录下添加 Markdown 文件，更新 authors.yml 中的作者信息
4. 修改首页：编辑 src/pages/index.tsx 和 src/components/HomepageFeatures/index.tsx
5. 调整主题：编辑 src/css/custom.css 中的 CSS 变量修改配色方案