# zip-md2pdf-web-project

**Repository Path**: aylerh/zip-md2pdf-web-project

## Basic Information

- **Project Name**: zip-md2pdf-web-project
- **Description**: # md在线编辑与pdf对比转换平台
## 特色功能
打开压缩包的md（首个发现的md，及对应的图片）；
html式表格转换为竖线式，且合并单元格自动向下复制填充；
自动清洗符号：如显示为$数字$、罗马符号等内容；
pdf导出功能：md的zip压缩包-》可搜索文本的pdf；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# md在线编辑与pdf对比转换平台
主要功能：（1）转换：md的zip压缩包-》可搜索文本的pdf；（2）pdf和md对比查看；

## 特色功能
* 打开压缩包的md（首个发现的md，及对应的图片）；
* markdown文件中的html式表格转换为竖线式，且合并单元格自动向下复制填充；
* 自动清洗符号：如显示为$数字$、罗马符号等内容；
* pdf导出功能：md的zip压缩包-》可搜索文本的pdf；

## 主要解决问题
* 压缩包md的预览与pdf转换问题；
* paddleocr-vl等ocr识别的html式表格md预览不好；
* gemini3识别的md预览问题：美元等符号不能正常预览；

# 部署
## 拉取代码
```
git clone https://gitee.com/aylerh/zip-md2pdf-web-project.git
cd zip-md2pdf-web-project
```
## 准备.env
```
cp .env_copy .env
```

## 正式部署-docker compose
```
# 1. 停止并移除旧容器（如果有）
docker compose down

# 2. 重新构建并启动
docker compose up -d --build

# 3. 查看状态
docker ps
```
### 打包生成的镜像
镜像（371M）：zip-md2pdf-web

## 网页访问
[访问链接-如：](127.0.0.1:8004)
```
127.0.0.1:OUTER_PORT
```
主页-md复制与编辑模式：
![2](images/2.png)

pdf对比模式：
![1](images/1.png)
## 文件结构目录
```
/
├── .env                   # 新增：定义端口变量
├── main.py                # FastAPI 后端核心逻辑 (包含首页路由与 PDF 转换接口)
├── index.html             # 前端单页面应用 (编辑器、对比模式、导出逻辑)
├── requirements.txt       # Python 依赖清单 (WeasyPrint, FastAPI 等)
├── Dockerfile             # Docker 镜像构建配置文件
└── docker-compose.yml     # Docker 容器编排配置文件
```

## 介绍
本项目是一个专为处理 **文档 OCR 识别结果（可处理带md的压缩包）** 而设计的**轻量级 Web 智能编辑器**。它集成了实时预览、多格式兼容、符号自动化处理及原件对比功能。

以下是该项目的核心功能、技术架构及痛点解决总结：

### 一、 实现功能 (Core Features)

1.  **PDF 双栏对比模式**：支持左右分栏布局，左侧加载原始 PDF 扫描件，右侧进行 Markdown 编辑，实现“边看原件边修校”。
2.  **HTML 表格矩阵修复**：通过专有的矩阵映射算法，将 OCR 识别出的带有合并单元格（`rowspan/colspan`）的复杂 HTML 表格完美转换为标准 Markdown 竖线表格。
3.  **LaTeX 符号暴力清洗**：针对石化文档中高频出现的特殊符号（如 $0^{\circ} \sim 180^{\circ}$、$\delta$、$\phi$、$\pm$ 等），一键将混乱的 LaTeX 源码替换为易读的标准工程符号。
4.  **智能编码转换**：自动检测 TXT 编码，兼容 UTF-8 和 GBK，彻底解决 Windows 环境下文本加载乱码的问题。
5.  **多格式资源管理**：支持直接加载 `.md`、`.txt` 以及 `.zip` 压缩包（自动提取包内文档），并支持编辑后的异步导出与保存。
6.  **响应式 UI 适配**：编辑器能够根据 PDF 窗口的开启/关闭动态调整宽度，确保宽表格在窄屏幕下也能横向滚动而不发生挤压。

### 二、 采用技术 (Technical Stack)

*   **Vditor (Markdown 引擎)**：作为核心编辑器内核，提供 IR (即时渲染) 和 SV (分栏预览) 两种模式，支持复杂的数学公式 (MathJax) 和代码高亮。
*   **Turndown (转换工具)**：用于将基础 HTML 标签平滑转换为 Markdown 语法。
*   **JSZip (文件处理)**：实现前端浏览器侧直接解析和重组 ZIP 压缩包内容。
*   **FileSaver.js**：实现前端 Blob 数据流的本地持久化保存。
*   **Web API (TextDecoder & URL.createObjectURL)**：
    *   利用 `TextDecoder` 的 `fatal` 模式实现编码自动回退（UTF-8 -> GBK）。
    *   利用 `createObjectURL` 实现 PDF 文件的零上传、零服务器存储实时预览。
*   **原生 JS 矩阵算法**：独立实现的 HTML Table 解析算法，通过虚拟坐标系处理 HTML 单元格的重叠与合并逻辑。
*   **docx (DOCX 生成)**：使用原生 JS 库直接构建 Word 文档，利用二进制流处理技术将 ZIP 中的图片直接嵌入 DOCX，无需中间转换，确保格式稳定。

### 三、 解决的核心痛点 (Pain Points Addressed)

1.  **OCR 符号混乱**：
    *   **痛点**：OCR 经常将“度”识别为 `^{\circ}`，将波浪号识别为 `\sim`，导致文档满是 `$` 符号。
    *   **解决**：通过自定义正则清洗引擎，一键物理切除 LaTeX 外壳，还原为工程人员习惯的纯文本符号。

2.  **复杂表格结构丢失**：
    *   **痛点**：普通转换工具遇到带“合并单元格”的表格会直接崩坏或数据错位。
    *   **解决**：采用“空间矩阵算法”，先还原表格物理排版，再重构 Markdown 竖线对齐，确保结构不乱。
    
3.  **DOCX 导出图片丢失**：
    *   **痛点**：Markdown 转 Word 时，ZIP 包内的相对路径图片（如 `ocr_images/1.jpg`）无法被识别。
    *   **解决**：在前端直接从 ZIP 读取二进制流嵌入 Word，支持模糊路径查找，彻底解决缺图问题。

4.  **校对效率低下**：
    *   **痛点**：用户需要在 PDF 阅读器和编辑器之间来回切换窗口。
    *   **解决**：实现单页面内分栏同步显示，并优化了“三屏/白屏”布局逻辑，确保编辑器在分栏状态下依然保持极高性能。

5.  **中文乱码烦恼**：
    *   **痛点**：国内石化工程文档多为旧版 GBK 编码。
    *   **解决**：内置智能解码器，用户无需关心文件编码，直接拖入即可正确显示中文。

6.  **界面可用性差**：
    *   **痛点**：许多编辑器在屏幕变窄时会将表格挤压成“一列”，无法阅读。
    *   **解决**：强制解除 CSS 宽度限制，支持表格溢出滚动，保证了石化行业长表格的阅读体验。