# mdeditor

**Repository Path**: liudc0810/mdeditor

## Basic Information

- **Project Name**: mdeditor
- **Description**: 用go语言编写的markdown文件编辑器，参照了 https://github/lengyi/lengyi-markdown-editor的html版本，在此感谢。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# Markdown 编辑器

一款 Go 语言驱动的 Markdown 写作工具。单个二进制文件，浏览器即开即用。<br>

## 目录

- [功能概览](#功能概览)
- [快速开始](#快速开始)
- [架构](#架构)
- [API 文档](#api-文档)
- [构建与发布](#构建与发布)
- [技术栈](#技术栈)
- [许可](#许可)

---

## 功能概览

### ✍️ Markdown 编辑器

- **实时预览** — 左侧编辑，右侧实时渲染，支持同步滚动
- **三种布局模式** — 编辑+预览 / 仅编辑 / 仅预览
- **可拖拽分隔栏** — 自由调整编辑器和预览区域大小
- **富文本工具栏** — 标题（H1–H6）、粗体、斜体、下划线、删除线、上/下标、引用、列表（有序/无序/任务列表）、代码（行内/代码块）、链接、图片、表格（可视化 8×8 网格选择器）
- **撤销/重做** — Ctrl+Z / Ctrl+Y，历史记录最多 100 步
- **查找替换** — Ctrl+F 打开查找面板，支持查找下一个、替换单个、全部替换
- **自动保存** — 输入后 500ms 自动保存到后端，同时保留 localStorage 兜底
- **文件导入** — 拖拽或点击导入 `.md` / `.markdown` / `.txt` 文件
- **图片插入** — URL 链接或本地文件上传（Base64 嵌入），拖拽图片自动插入
- **清除文档** — 一键清空当前内容，带确认对话框

### 🧮 数学公式

- **KaTeX 引擎** — 支持行内 `$...$` 和块级 `$$...$$` 数学公式
- **公式保护** — 后端渲染时自动提取数学公式，防止 goldmark 错误解析

### 📊 图表

- **Mermaid 图表** — 支持思维导图（Mindmap）和流程图（Flowchart）模板
- **深色/亮色主题同步** — Mermaid 渲染自动跟随编辑器主题

### 📤 多格式导出

| 格式 | 方式 | 说明 |
|------|------|------|
| **Markdown** (`.md`) | 后端 API | 直接返回原始 Markdown |
| **Word** (`.docx`) | 后端 API | **真正的 OOXML 格式**，纯 Go 标准库构建（`archive/zip`），零外部依赖 |
| **HTML** (`.html`) | 后端 API | 独立 HTML 页面，内联 KaTeX CSS + JS，数学公式正常显示 |
| **PDF** (`.pdf`) | 浏览器打印 | 调用 `window.print()`，用户选择"另存为 PDF" |
| **图片** (`.png`) | 浏览器端 | 5 种比例预设（9:16, 4:5, 3:4, 1:1, 16:9），支持长图模式 |

### 🌐 网页转 Markdown

- **URL 抓取** — 输入网页地址，自动下载并转换为 Markdown
- **SSRF 防护** — DNS 解析并阻止私有/内网 IP 访问（RFC 1918、回环、链路本地、运营商级 NAT 等）
- **反爬虫规避** — 随机 User-Agent 轮换 + 站点特定 Referer（知乎、微信公众号、简书）
- **自动重试** — 最多 3 次，指数退避
- **内容提取** — 自动识别 `<article>`、`<main>`、正文容器类名，清理脚本、样式、导航、侧栏等无关元素
- **元数据提取** — 标题、作者、发布日期
- **手动输入备选** — 可粘贴 HTML 源码进行转换

### 📁 文档管理

- **侧边栏文档列表** — 查看所有文档，按更新时间倒序排列
- **新建文档** — 自动生成唯一 ID
- **切换文档** — 自动保存当前文档
- **删除文档** — 带确认对话框，自动切换到下一个可用文档
- **本地存储兜底** — 后端不可用时内容保存到 localStorage

### 🎨 主题 & 国际化

- **亮色/深色主题** — 一键切换，CSS 变量实现，偏好记忆在 localStorage
- **10 种语言** — 简体中文、繁体中文、英语、日语、韩语、西班牙语、法语、德语、俄语、葡萄牙语
- **自动检测** — 首次使用自动匹配浏览器语言

### 🛡️ 安全

- **X-Content-Type-Options: nosniff** — 防止 MIME 类型嗅探
- **X-Frame-Options: DENY** — 防止点击劫持
- **CORS** — 跨域支持
- **Panic 恢复** — 中间件捕获 panic，返回 500 JSON 错误
- **请求体大小限制** — 所有 POST/PUT 端点限制 10 MB
- **清理文件名** — 导出文件名去除不安全字符，限制 200 字符
- **公式 XSS 防护** — 数学公式内容经 HTML 转义后插入页面

---

## 快速开始

### 方法一：从源码构建

```bash
# 克隆仓库
git clone https://gitee.com/liudc0810/mdeditor.git
cd mdeditor

# 构建
go build -o mdeditor .

# 运行
./mdeditor --port 8090
```

### 方法二：使用 Makefile

```bash
make build   # 构建
make run     # 构建并运行（默认 :8090）
```

### 方法三：跨平台发布版

```bash
make release  # 构建 linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64
```

### 命令行参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--port` | `8090` | HTTP 服务器端口 |
| `--data-dir` | `./data` | 文档存储目录 |

启动后访问 `http://localhost:8090` 即可使用。

---

## 架构

### 分层结构

```
main.go                          # 入口：flag 解析 + go:embed + 优雅关闭
└── internal/server/server.go    # HTTP 服务器 + 路由 + 中间件
    └── internal/handler/        # API 处理器
        ├── document.go          #   文档 CRUD
        ├── render.go            #   Markdown → HTML 渲染
        ├── export.go            #   导出 .md / .docx / .html
        └── web2md.go            #   网页 → Markdown
    ├── internal/store/          # 文档存储
    │   ├── store.go             #   Store 接口定义
    │   └── filestore.go         #   文件系统实现
    ├── internal/render/         # Markdown 渲染管线
    │   ├── markdown.go          #   goldmark 渲染
    │   └── math.go              #   数学公式保护/恢复
    ├── internal/export/         # 导出生成器
    │   ├── html.go              #   独立 HTML 页面
    │   └── docx.go              #   OOXML .docx 生成器
    └── internal/web2md/         # 网页抓取与转换
        ├── fetcher.go           #   HTTP 抓取 + SSRF 防护
        └── converter.go         #   HTML → Markdown 转换
web/                             # 前端（go:embed → 嵌入二进制）
├── index.html                   # 单文件应用（含全部 CSS + JS）
├── i18n.js                      # 国际化字典（10 语言）
└── vendor/                      # CDN 依赖本地化
    ├── katex/                   #   KaTeX 数学公式渲染
    ├── mermaid/                 #   Mermaid 图表渲染
    └── dom-to-image-more/       #   PNG 截图导出
```

### 数据存储

- 每篇文档存储为两个文件：
  - `<id>.meta.json` — 元数据（ID、文件名、更新时间、字数）
  - `<id>.md` — Markdown 正文
- ID 为 32 位十六进制字符串（密码学安全随机生成）
- 使用 `sync.RWMutex` 保障并发安全

### 前后端分工

| 层 | 职责 |
|----|------|
| **Go 后端** | Markdown 渲染（goldmark）、文档存储（文件系统）、文件导出（.md/.docx/.html）、网页抓取转换 |
| **前端** | 编辑交互、实时预览、KaTeX/Mermaid/PNG 截图渲染、主题/语言偏好（localStorage） |

---

## API 文档

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/health` | 健康检查 |
| `GET` | `/api/v1/documents` | 获取文档列表（不含内容） |
| `POST` | `/api/v1/documents` | 创建文档 |
| `GET` | `/api/v1/documents/{id}` | 获取单个文档（含内容） |
| `PUT` | `/api/v1/documents/{id}` | 更新文档（部分更新，content/filename 可选） |
| `DELETE` | `/api/v1/documents/{id}` | 删除文档 |
| `POST` | `/api/v1/render` | Markdown → HTML 渲染 |
| `POST` | `/api/v1/export/md` | 导出 Markdown 文件 |
| `POST` | `/api/v1/export/doc` | 导出 Word 文档（.docx） |
| `POST` | `/api/v1/export/html` | 导出独立 HTML 页面 |
| `POST` | `/api/v1/web2md` | 网页 URL → Markdown |

---

## 构建与发布

### 前提条件

- Go 1.24 或更高版本
- 无需其他运行时依赖

### Makefile 命令

| 命令 | 说明 |
|------|------|
| `make build` | 构建当前平台可执行文件 |
| `make run` | 构建并运行（端口 8090） |
| `make clean` | 删除可执行文件 |
| `make clean-data` | 删除数据目录 |
| `make test` | 运行 `go vet` + `go build` + `go test` |
| `make release` | 构建多平台发布版（5 个平台），打包为 `.tar.gz` |

---

## 技术栈

### Go 后端

| 依赖 | 用途 |
|------|------|
| `github.com/yuin/goldmark v1.8.2` | Markdown → HTML 渲染，GFM + 脚注扩展 |
| `golang.org/x/net v0.28.0` | HTML 解析（docx 导出 + web2md 转换） |
| Go 标准库 | HTTP 服务器、JSON 编码、文件 I/O、crypto/rand、archive/zip |

### 前端（嵌入二进制）

| 库 | 用途 |
|----|------|
| **KaTeX** | 数学公式渲染 |
| **Mermaid** | 图表渲染 |
| **dom-to-image-more** | 导出 PNG 截图 |

---

## 许可

本项目基于 MIT 许可证开源。