中文 | English
CodeDocs 编程文档
一些技术人的编程文档网站 —— 涵盖后端、前端、算法
简介
CodeDocs 是一个基于 Docusaurus 3 构建的中文技术文档站，采用 React 18 + TypeScript 技术栈。
功能特性
- 📚 系统化文档 — 后端（Spring Boot / Spring Cloud）、前端（React / Vue）、算法（LeetCode）分门别类
- ⚡ 全文检索 — 集成 Algolia DocSearch，毫秒级搜索
- 🔢 数学公式 — 通过 KaTeX 渲染 LaTeX 数学公式（
remark-math+rehype-katex） - 🌐 国际化 — 支持中文 / English 双语切换（
i18n） - 🌙 深色模式 — 内置亮色 / 深色主题自动切换
- 🚀 CI/CD — GitHub Actions 自动构建 + FTP 部署
技术栈
| 类别 | 技术 |
|---|---|
| 框架 | Docusaurus 3.7 |
| 前端 | 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
安装 & 启动
# 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 进行全文检索，需要配置以下环境变量：
# 创建 .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 密码 |
手动部署
npm run build
# 产物输出到 ./build/ 目录，部署到任意静态服务器即可
撰写文档
新增文档页
在 docs/ 对应目录下创建 .md 或 .mdx 文件：
---
sidebar_position: 1
---
# 文档标题
这里是文档内容。
- 纯 Markdown 内容使用
.md扩展名 - 包含 JSX 组件（如
<Tabs>、<span style={{}}>等）的文件须使用.mdx扩展名
数学公式
支持 LaTeX 语法，通过 KaTeX 渲染：
行内公式：$E = mc^2$
独立公式块：
$$
\int_0^\infty f(x)\,dx
$$
新增博客
在 blog/ 目录下创建 Markdown 文件：
---
slug: my-post
title: 文章标题
author: 作者名
tags: [标签1, 标签2]
---
摘要内容。
<!--truncate-->
正文内容。
开源协议
MIT © Yaoyuan Chu