# markDown文本编辑器

**Repository Path**: xie-yaozu/mark-down-text-editor

## Basic Information

- **Project Name**: markDown文本编辑器
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-04-10
- **Last Updated**: 2025-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown 编辑器项目文档

## 1. 项目概述

### 1.1 项目简介
本项目是一个基于 Vue3 + TypeScript 开发的在线 Markdown 编辑器，提供实时预览、主题切换、多种编辑工具等功能，旨在提供一个简洁、高效的 Markdown 写作环境。

### 1.2 功能特性
- ✨ 实时预览 Markdown 渲染效果
- 🎨 支持多种主题切换（GitHub、暗黑、护眼等）
- 📝 丰富的编辑工具栏
- 📋 支持图片粘贴上传
- 💾 自动保存功能
- 📦 导出多种格式（MD、PDF、HTML）
- 📋 多种文档模板
- 🔍 文档大纲导航
- 📊 字数统计功能
- 🔄 协同编辑功能

### 1.3 技术栈
- 前端框架：Vue 3
- 开发语言：TypeScript
- 构建工具：Vite
- Markdown 解析：Marked
- 代码高亮：Highlight.js
- 样式处理：SCSS
- 包管理器：pnpm
- 后端：Node.js
- WebSocket：ws

## 2. 项目结构

### 2.1 目录结构
```
markdown-editor/
├── src/
│   ├── components/        # 组件目录
│   ├── hooks/            # 自定义 hooks
│   ├── styles/           # 样式文件
│   ├── utils/            # 工具函数
│   ├── types/            # TypeScript 类型定义
│   ├── App.vue           # 根组件
│   └── main.ts           # 入口文件
├── public/               # 静态资源
├── docs/                 # 项目文档
├── tests/                # 测试文件
└── package.json          # 项目配置文件
```

### 2.2 核心模块
1. 编辑器模块
   - 文本编辑区
   - 工具栏
   - 快捷键处理

2. 预览模块
   - Markdown 解析
   - 实时渲染
   - 样式处理

3. 工具模块
   - 文件导出
   - 图片处理
   - 自动保存

## 3. 开发规范

### 3.1 代码规范
1. **命名规范**
   - 组件名：PascalCase（如 MarkdownEditor）
   - 变量名：camelCase（如 editorContent）
   - 常量名：UPPER_CASE（如 MAX_FILE_SIZE）

2. **文件组织**
   - 每个组件一个文件
   - 相关的工具函数放在 utils 目录
   - 类型定义放在 types 目录

3. **注释规范**
   ```typescript
   /**
    * 函数描述
    * @param {string} param - 参数描述
    * @returns {void} 返回值描述
    */
   ```

### 3.2 Git 规范
1. **分支管理**
   - main：主分支，用于发布
   - develop：开发分支
   - feature/*：功能分支
   - fix/*：修复分支

2. **提交信息规范**
   ```
   feat: 添加新功能
   fix: 修复问题
   docs: 修改文档
   style: 修改样式
   refactor: 代码重构
   test: 添加测试
   chore: 修改构建过程或辅助工具
   ```

## 4. 开发流程

### 4.1 环境搭建
1. 克隆项目
   ```bash
   git clone <repository-url>
   cd markdown-editor
   ```

2. 安装依赖
   ```bash
   pnpm install
   ```

3. 启动开发服务器
   ```bash
   pnpm dev
   ```

### 4.2 开发步骤
1. 从 develop 分支创建新的功能分支
2. 开发新功能
3. 编写测试用例
4. 提交代码并创建 Pull Request
5. 代码审查
6. 合并到 develop 分支

## 5. 部署说明

### 5.1 构建项目
```bash
# 构建生产环境版本
pnpm build

# 预览构建结果
pnpm preview
```

### 5.2 部署步骤
1. 构建项目生成 dist 目录
2. 将 dist 目录部署到服务器
3. 配置 nginx 或其他 Web 服务器
4. 配置 HTTPS 证书（推荐）

## 6. 测试规范

### 6.1 单元测试
- 使用 Vitest 进行单元测试
- 测试文件以 .test.ts 结尾
- 测试覆盖率要求：80% 以上

### 6.2 E2E 测试
- 使用 Cypress 进行端到端测试
- 测试关键用户流程
- 测试跨浏览器兼容性

## 7. 版本发布

### 7.1 版本号规范
采用语义化版本号：主版本号.次版本号.修订号
- 主版本号：不兼容的 API 修改
- 次版本号：向下兼容的功能性新增
- 修订号：向下兼容的问题修正

### 7.2 发布流程
1. 更新版本号
2. 生成更新日志
3. 构建生产版本
4. 发布到 npm（如果需要）
5. 创建 Git 标签
6. 部署到生产环境

## 8. 常见问题

### 8.1 开发相关
1. 开发环境启动失败
   - 检查 Node.js 版本
   - 清除 node_modules 重新安装
   - 检查端口占用情况

2. 编译错误
   - 检查 TypeScript 类型定义
   - 更新依赖版本
   - 清除缓存重新构建

### 8.2 部署相关
1. 静态资源加载失败
   - 检查 base URL 配置
   - 检查资源路径是否正确
   - 检查服务器配置

2. 跨域问题
   - 配置 CORS 头
   - 检查代理设置
   - 调整安全策略

## 9. 联系方式

### 9.1 技术支持
- 项目负责人：[姓名]
- 邮箱：[邮箱地址]
- 技术群：[群号]

### 9.2 问题反馈
- GitHub Issues
- 邮件反馈
- 在线讨论组

## 10. 更新日志

### v1.0.0 (2024-01-01)
- 🎉 初始版本发布
- ✨ 基础编辑功能
- 🎨 多主题支持
- 📝 实时预览

### v1.1.0 (2024-01-15)
- ✨ 添加图片上传功能
- 🔧 优化编辑体验
- 🐛 修复已知问题

## 11. 贡献指南

### 11.1 如何贡献
1. Fork 项目
2. 创建功能分支
3. 提交变更
4. 创建 Pull Request

### 11.2 贡献规范
- 遵守代码规范
- 编写测试用例
- 更新文档
- 清晰的提交信息

## 12. 许可证
MIT License 

## 协同编辑功能实现

### 1. 实现原理
协同编辑功能基于 CRDT（Conflict-free Replicated Data Type）算法实现，主要包含以下几个部分：

1. **CRDT 算法**
   - 使用 Yjs 的 YATA（Yet Another Transformation Approach）算法
   - 支持去中心化的并发编辑
   - 自动处理编辑冲突
   - 保证最终一致性

2. **WebSocket 服务器**
   - 使用 `y-websocket` 包实现
   - 监听 1234 端口
   - 处理客户端连接和文档同步
   - 服务器断开后客户端仍可继续编辑

3. **客户端实现**
   - 使用 Yjs 的 `WebsocketProvider`
   - 自动重连机制
   - 实时文档同步
   - 支持离线编辑

### 2. 核心代码实现

#### 服务器端
```javascript
import { WebSocketServer } from 'ws'
import { setupWSConnection } from 'y-websocket'

const wss = new WebSocketServer({ port: 1234 })

wss.on('connection', (conn, req) => {
  setupWSConnection(conn, req)
})

console.log('WebSocket server running on ws://localhost:1234')
```

#### 客户端
```typescript
// Yjs 文档和连接管理
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

// 创建 Yjs 文档
const ydoc = new Y.Doc()
// 创建共享文本
const ytext = ydoc.getText('markdown')

// 创建 WebSocket 连接
const wsProvider = new WebsocketProvider(
  'ws://localhost:1234', // WebSocket 服务器地址
  'markdown-room', // 房间名称
  ydoc
)

// 监听远程更改
onMounted(() => {
  // 观察文本变化
  ytext.observe(event => {
    // 更新本地内容
    if (!event.transaction.local) {
      markdownContent.value = ytext.toString()
      updatePreview()
    }
  })

  // 初始化内容
  markdownContent.value = ytext.toString() || defaultContent
  updatePreview()
})

// 修改 handleInput 函数
const handleInput = (event: Event) => {
  const newContent = (event.target as HTMLTextAreaElement).value
  // 更新协同文档
  ytext.delete(0, ytext.length)
  ytext.insert(0, newContent)
  
  updatePreview()
  updateWordCount()
}

// 在组件卸载时清理
onUnmounted(() => {
  wsProvider.disconnect()
  ydoc.destroy()
})
```

### 3. 实现思路

1. **文档模型**
   - 使用 Yjs 的 `Doc` 类创建共享文档
   - 使用 `Text` 类型创建共享文本
   - 通过 `observe` 监听文档变化

2. **连接管理**
   - 使用 `WebsocketProvider` 管理 WebSocket 连接
   - 自动处理连接和重连
   - 支持多个房间的文档隔离

3. **内容同步**
   - 本地编辑时更新 Yjs 文档
   - Yjs 自动处理并发编辑
   - 通过观察者模式更新 UI

4. **状态管理**
   - Yjs 文档作为单一数据源
   - 本地状态与 Yjs 文档同步
   - 自动处理冲突和合并

### 4. 使用说明

1. 安装依赖：
```bash
npm install yjs y-websocket
```

2. 启动前端开发服务器：
```bash
npm run dev
```

3. 在多个浏览器窗口中打开应用，它们会自动同步内容。

### 5. 注意事项

1. **开发环境**
   - 开发时使用 `y-websocket` 包提供的 WebSocket 功能
   - 不需要单独启动 WebSocket 服务器

2. **生产环境**
   - 需要配置实际的 WebSocket 服务器地址
   - 建议使用 `wss://` 协议（WebSocket Secure）
   - 需要配置相应的域名和 SSL 证书

3. **性能优化**
   - 使用 Yjs 的批量更新
   - 避免频繁的文档操作
   - 合理使用观察者

### 6. 技术优势

1. **CRDT 算法**
   - 去中心化的并发编辑
   - 自动合并更改
   - 保证最终一致性
   - 支持离线编辑
   - 无需中心服务器协调

2. **实时同步**
   - 低延迟的文档同步
   - 支持离线编辑
   - 自动重连机制
   - 断网后仍可继续编辑

3. **可扩展性**
   - 支持多种数据类型
   - 支持自定义同步策略
   - 支持多种后端
   - 支持 P2P 连接 

4. **注意的问题**
- 发布上线的地址：
   需要将 ws://localhost:1234 改为实际的 WebSocket 服务器地址
   例如：wss://your-domain.com/yjs（注意使用 wss:// 而不是 ws://，因为生产环境需要加密）
   需要配置相应的域名和 SSL 证书
- 去掉 WebSocket 代码的影响：
   如果去掉 WebsocketProvider，协同编辑功能将无法工作
   每个客户端将只能看到自己的编辑
   不同客户端之间的更改将无法同步
   但基本的 Markdown 编辑功能仍然可以使用
- 当前的安全性问题：
   目前任何人都可以编辑，没有用户认证
   所有编辑都会合并到一起
   没有权限控制
   没有用户标识