中文 | [English](./README.md)
CodeDocs 编程文档
一些技术人的编程文档网站 —— 涵盖后端、前端、算法
---
## 简介
CodeDocs 是一个基于 [Docusaurus 3](https://docusaurus.io/) 构建的中文技术文档站，采用 React 18 + TypeScript 技术栈。
**官网**：[docs.yaoyuan.io](http://docs.yaoyuan.io/)
## 功能特性
- 📚 **系统化文档** — 后端（Spring Boot / Spring Cloud）、前端（React / Vue）、算法（LeetCode）分门别类
- ⚡ **全文检索** — 集成 [Algolia DocSearch](https://docsearch.algolia.com/)，毫秒级搜索
- 🔢 **数学公式** — 通过 KaTeX 渲染 LaTeX 数学公式（`remark-math` + `rehype-katex`）
- 🌐 **国际化** — 支持中文 / English 双语切换（`i18n`）
- 🌙 **深色模式** — 内置亮色 / 深色主题自动切换
- 🚀 **CI/CD** — GitHub Actions 自动构建 + FTP 部署
## 技术栈
| 类别 | 技术 |
|------|------|
| 框架 | [Docusaurus 3.7](https://docusaurus.io/) |
| 前端 | React 18, TypeScript 5, MDX 3 |
| 样式 | CSS Modules, Infima |
| 数学渲染 | KaTeX (remark-math 6 + rehype-katex 7) |
| 搜索 | Algolia DocSearch |
| 构建 | Node.js 20, npm |
| CI/CD | GitHub Actions → FTP Deploy |
| 代码规范 | TypeScript 严格模式, ESLint (可扩展) |
## 目录结构
```
code-docs/
├── docs/ # 文档内容
│ ├── intro-docs.mdx # 文档首页介绍
│ ├── backend-doc/ # 后端文档
│ │ ├── SpringBoot/ # Spring Boot 系列
│ │ └── SpringCloud/ # Spring Cloud 系列
│ ├── frontend-doc/ # 前端文档
│ │ ├── React/ # React 系列
│ │ └── Vue/ # Vue 系列
│ └── LeetCode/ # 算法题解
│ ├── 1 - 100/ # 第 1 ~ 100 题
│ ├── 100 - 200/ # 第 100 ~ 200 题
│ └── CodingInterviews/ # 剑指 Offer 系列
├── blog/ # 博客文章
├── src/
│ ├── components/ # React 组件 (TSX)
│ ├── css/ # 全局样式
│ └── pages/ # 自定义页面 (TSX)
├── static/ # 静态资源 (图片等)
├── docusaurus.config.ts # Docusaurus 配置 (TypeScript)
├── sidebars.ts # 侧边栏配置
├── tsconfig.json # TypeScript 配置
├── babel.config.js # Babel 配置
├── package.json # 依赖管理
└── .github/workflows/deploy.yml # CI/CD 工作流
```
## 快速开始
### 环境要求
- **Node.js** >= 20 (推荐 LTS 版本)
- **npm** >= 10
- **Git**
### 安装 & 启动
```bash
# 1. 克隆仓库
git clone https://github.com/chuyaoyuan/code-docs.git
cd code-docs
# 2. 安装依赖
npm install
# 3. 本地开发 (热更新)
npm run start
# 4. 访问
# http://localhost:3000
```
### 常用命令
| 命令 | 说明 |
|------|------|
| `npm run start` | 启动本地开发服务器（热更新） |
| `npm run build` | 生产环境构建 |
| `npm run serve` | 预览生产构建产物 |
| `npm run typecheck` | TypeScript 类型检查 |
| `npm run write-translations` | 生成 i18n 翻译模板 |
| `npm run clear` | 清除 Docusaurus 缓存 |
## 环境变量
本项目使用 Algolia DocSearch 进行全文检索，需要配置以下环境变量：
```bash
# 创建 .env.local 文件 (已在 .gitignore 中排除)
ALGOLIA_APP_ID=your_app_id
ALGOLIA_API_KEY=your_search_only_api_key
```
> 本地开发时通过 `dotenv` 自动加载 `.env.local`。CI 环境中通过 GitHub Secrets 注入。
## 部署
### GitHub Actions 自动部署
项目配置了 GitHub Actions 工作流（`.github/workflows/deploy.yml`）：
- **PR → `main`**：仅执行构建校验，不部署
- **Push → `main`**：构建 + FTP 部署到生产服务器
需要在 GitHub 仓库 **Settings → Secrets** 中配置：
| Secret | 说明 |
|--------|------|
| `ALGOLIA_APP_ID` | Algolia Application ID |
| `ALGOLIA_API_KEY` | Algolia Search-Only API Key |
| `FTP_SERVER` | FTP 服务器地址 |
| `FTP_USER` | FTP 用户名 |
| `FTP_PWD` | FTP 密码 |
### 手动部署
```bash
npm run build
# 产物输出到 ./build/ 目录，部署到任意静态服务器即可
```
## 撰写文档
### 新增文档页
在 `docs/` 对应目录下创建 `.md` 或 `.mdx` 文件：
```md
---
sidebar_position: 1
---
# 文档标题
这里是文档内容。
```
- 纯 Markdown 内容使用 `.md` 扩展名
- 包含 JSX 组件（如 ``、`` 等）的文件须使用 `.mdx` 扩展名
### 数学公式
支持 LaTeX 语法，通过 KaTeX 渲染：
```md
行内公式：$E = mc^2$
独立公式块：
$$
\int_0^\infty f(x)\,dx
$$
```
### 新增博客
在 `blog/` 目录下创建 Markdown 文件：
```md
---
slug: my-post
title: 文章标题
author: 作者名
tags: [标签1, 标签2]
---
摘要内容。
正文内容。
```
## 开源协议
[MIT](https://opensource.org/licenses/MIT) © Yaoyuan Chu