# f2e-easy-docs

**Repository Path**: f2e-server/f2e-easy-docs

## Basic Information

- **Project Name**: f2e-easy-docs
- **Description**: f2e-server 创建的简单文档分享工具，支持快速导出方便web服务配置
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-12-24
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# f2e-easy-docs

一个基于 React + TypeScript + Node.js 的现代化文档管理系统，支持通过编辑 Markdown 文档生成静态文档站点。

## 📋 项目概述

f2e-easy-docs 是一个功能完整的文档管理平台，提供文档编辑、预览、导出和部署等一站式解决方案。项目采用前后端分离架构，前端使用 React + Ant Design，后端基于 f2e-server3 框架构建。

## ✨ 核心功能

### 🎯 管理端功能
- **用户管理**：支持用户登录、角色管理和权限控制
- **站点管理**：创建、修改、删除文档站点，支持导入导出
- **文档管理**：创建、编辑 Markdown 文档，支持图片和附件上传
- **实时预览**：分屏编辑模式，左侧编辑，右侧实时预览
- **文档树管理**：支持文档层级结构，拖拽排序和移动

### 📤 导出功能
- **站点导出**：一键导出完整站点，包含所有文档和资源
- **文档导出**：支持单个文档导出
- **静态部署**：生成的文档可直接部署到 Nginx 等静态服务器

### 🚀 部署功能
- **静态站点**：导出为单文件 HTML，包含所有 CSS 和 JS
- **Nginx 部署**：提供完整的部署配置参考
- **文件结构**：
  ```
  <项目名称>.zip
  └─ docs/
      ├─ files/     # 图片附件等文件存储位置
      └─ index.html # 站点HTML、CSS、JS全部bundle在 index.html
  ```

## 🛠️ 技术栈

### 前端技术
- **React 18** - 用户界面框架
- **TypeScript** - 类型安全的 JavaScript
- **Ant Design 5** - UI 组件库
- **CodeMirror 6** - 代码编辑器
- **React Markdown** - Markdown 渲染
- **React Router 7** - 路由管理
- **Tailwind CSS** - 样式框架

### 后端技术
- **f2e-server3** - 基于 Node.js 的服务器框架
- **f2e-middle-rbac** - 基于角色的访问控制中间件
- **Archiver** - 文件压缩
- **Unzipper** - 文件解压
- **Marked** - Markdown 解析器
- **Clean CSS** - CSS 压缩

### 开发工具
- **ESBuild** - 快速构建工具
- **PostCSS** - CSS 处理
- **Chokidar** - 文件监听
- **Highlight.js** - 代码高亮

## 📁 项目结构

```
f2e-easy-docs/
├── src/                          # 前端源码
│   ├── components/               # React 组件
│   │   ├── AppList/             # 应用列表组件
│   │   ├── Editor/              # 编辑器组件
│   │   │   ├── EditorMarkdown/  # Markdown 编辑器
│   │   │   └── EditorTree.tsx   # 文档树组件
│   │   ├── Header/              # 头部组件
│   │   └── Preview/             # 预览组件
│   ├── apis/                    # API 接口
│   ├── utils/                   # 工具函数
│   └── App.tsx                  # 主应用组件
├── serve/                       # 后端服务
│   ├── actions/                 # 业务逻辑
│   │   ├── app.ts              # 应用管理
│   │   ├── tree.ts             # 文档树管理
│   │   ├── upload.ts           # 文件上传
│   │   └── profile.ts          # 用户信息
│   ├── preview/                 # 预览功能
│   ├── validators/              # 数据验证
│   └── interface.ts            # 类型定义
├── ssl/                        # SSL 证书
└── package.json                # 项目配置
```

## 🚀 快速开始

### 环境要求
- Node.js >= 16.0.0
- Chrome >= 70 (推荐使用最新版本)

### 安装依赖
```bash
npm install
```

### 开发模式
```bash
npm run dev
```

### 生产模式
```bash
npm run start
```

### 编译
```bash
npm run compile
```

## 📖 使用指南

### 1. 创建站点
1. 登录系统后，点击"新建站点"按钮
2. 填写站点名称、描述等基本信息
3. 设置是否启用目录功能

### 2. 编辑文档
1. 在站点列表中选择要编辑的站点
2. 使用左侧文档树创建和管理文档结构
3. 在右侧编辑器中编写 Markdown 内容
4. 支持实时预览和快捷键操作

### 3. 上传文件
- **图片上传**：直接拖拽或点击上传按钮
- **附件上传**：支持各种文件格式
- **自动处理**：重复文件名自动添加时间戳

### 4. 导出部署
1. 点击"导出"按钮下载站点压缩包
2. 解压到 Nginx 根目录
3. 访问 `/docs/` 路径查看文档站点

## 🔧 配置说明

### 服务器配置
```bash
# 启动参数
npm run dev -p 8999 -d ./docs -m dev -l DEBUG

# 参数说明
-p, --port <port>     端口号 (默认: 8999)
-d, --dir <dir>       文档存储根路径 (默认: ./.f2e_cache/docs)
-m, --mode <mode>     构建模式 (prod/dev)
-l, --level <level>   日志级别 (INFO/DEBUG)
```

### Nginx 部署配置
```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location /docs/ {
        alias /path/to/docs/;
        try_files $uri $uri/ /docs/index.html;
    }
}
```

## 🎨 功能特性

### 编辑器功能
- **语法高亮**：支持多种编程语言
- **实时预览**：分屏编辑，所见即所得
- **快捷键支持**：Ctrl+S 保存，Ctrl+Z 撤销等
- **全屏模式**：支持全屏编辑
- **拖拽上传**：支持文件拖拽上传

### 文档管理
- **层级结构**：支持多级文档目录
- **拖拽排序**：文档树支持拖拽移动
- **搜索功能**：快速定位文档
- **版本控制**：自动保存和恢复

### 权限管理
- **用户角色**：支持多用户协作
- **权限控制**：基于角色的访问控制
- **安全认证**：支持 SSL 加密

## 🔍 API 接口

### 应用管理
- `POST /api/create_app` - 创建站点
- `POST /api/update_app` - 更新站点
- `POST /api/delete_app` - 删除站点
- `GET /api/app_detail` - 获取站点详情

### 文档管理
- `GET /api/get_doc` - 获取文档内容
- `POST /api/save_doc` - 保存文档
- `POST /api/save_dir` - 保存文档目录
- `POST /api/delete_dir` - 删除文档
- `POST /api/move_dir` - 移动文档

### 文件管理
- `POST /api/upload` - 上传文件
- `POST /api/import` - 导入站点
- `GET /export/:app_id` - 导出站点

## 🐛 问题排查

### 常见问题
1. **Chrome 版本过低**：请升级到 Chrome 70 以上版本
2. **文件上传失败**：检查文件大小和格式限制
3. **预览页面空白**：检查文档路径和权限设置

### 日志查看
```bash
# 开启调试模式
npm run dev -l DEBUG
```

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 👨‍💻 作者

**shy2850** - [GitHub](https://github.com/shy2850)

## 🙏 致谢

感谢以下开源项目的支持：
- [React](https://reactjs.org/)
- [Ant Design](https://ant.design/)
- [CodeMirror](https://codemirror.net/)
- [f2e-server3](https://github.com/f2e-server/f2e-server3)
- [Marked](https://marked.js.org/)

---

如有问题或建议，欢迎提交 Issue 或 Pull Request！