200 lines
5.6 KiB
Markdown
200 lines
5.6 KiB
Markdown
中文 | [English](./README.md)
|
||
|
||
<h1 align="center">CodeDocs 编程文档</h1>
|
||
<h3 align="center">一些技术人的编程文档网站 —— 涵盖后端、前端、算法</h3>
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License MIT"></a>
|
||
<img src="https://img.shields.io/badge/Docusaurus-3.7-green" alt="Docusaurus 3.7">
|
||
<img src="https://img.shields.io/badge/React-18-blue" alt="React 18">
|
||
<img src="https://img.shields.io/badge/TypeScript-5-blue" alt="TypeScript 5">
|
||
<img src="https://img.shields.io/badge/Node-%3E%3D20-brightgreen" alt="Node >= 20">
|
||
</p>
|
||
|
||
## 简介
|
||
|
||
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 组件（如 `<Tabs>`、`<span style={{}}>` 等）的文件须使用 `.mdx` 扩展名
|
||
|
||
### 数学公式
|
||
|
||
支持 LaTeX 语法，通过 KaTeX 渲染：
|
||
|
||
```md
|
||
行内公式：$E = mc^2$
|
||
|
||
独立公式块：
|
||
$$
|
||
\int_0^\infty f(x)\,dx
|
||
$$
|
||
```
|
||
|
||
### 新增博客
|
||
|
||
在 `blog/` 目录下创建 Markdown 文件：
|
||
|
||
```md
|
||
---
|
||
slug: my-post
|
||
title: 文章标题
|
||
author: 作者名
|
||
tags: [标签1, 标签2]
|
||
---
|
||
|
||
摘要内容。
|
||
<!--truncate-->
|
||
正文内容。
|
||
```
|
||
|
||
## 开源协议
|
||
|
||
[MIT](https://opensource.org/licenses/MIT) © Yaoyuan Chu
|