# md2docx-py-project

**Repository Path**: aylerh/md2docx-py-project

## Basic Information

- **Project Name**: md2docx-py-project
- **Description**: 功能：(1)md或zip(包含图片和md)转换为docx(2)同时支持docx2md; 
优点：（1）公式显示word公式工具；（2）对比显示；速度快；效果好；要求：（1）要求latex公式转为word框-MathML形式；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MD to DOCX Converter

基于 FastAPI 和 Python-Docx 的 Markdown 转 Word 工具。支持 LaTeX 公式、图片、表格及 ZIP 压缩包上传。

## 页面样式

### 主页
![1](./images/1.png)

## 优点
### md上前端功能
无标点合并：会将文件名保存中不支持的符号如\ / : * ? "< >替换为-

### docx2md
- 对齐样式保留；
- 智能脚注显示：通过预扫描定位脚注定义，智能切换标准脚注引用与 HTML 上标标签。如^[18]

## 快速启动

1. 确保已安装 Docker 和 Docker Compose。
2. 在项目根目录运行：
   ```powershell
   docker compose up --build
   ```
3. 访问 `http://localhost:8203`。

## 功能特性

- **Markdown 解析**：支持标题、列表、表格（标准及合并单元格表格）。【表格合并单元格-复制为相同内容】
- **ZIP 支持**：自动解压并识别包含图片的压缩包，解决相对路径引用问题。
- **LaTeX 公式**：将 LaTeX 转换为 Word 原生 OMML 公式，确保公式可编辑且排版精确。【word公式工具显示】
- **图片自适应**：支持 HTML 样式的图片标签，可控对齐方式及 `width` 展示比例。【图片可以插入进入docx】
- **现代 UI**：极致视觉享受，基于玻璃拟态设计的响应式 Web 界面。

## 注意
- 脚注显示：如果文中出现了 [^18]，但在文档的任何地方都找不到对应的脚注定义（比如在文档末尾写着 [^18]: 这是一个脚注），解析器就会认为这只是一个普通的文本符号，而不是脚注。 既然它被当作了普通文本【markdown-it 脚注插件机制】；

## 效果与低延迟

- **渲染效果优秀**：将 LaTeX 转换为 Word 原生 OMML 公式（而非图片），在 Word 中可直接编辑、复制与再次排版，保证输出文档的可维护性与美观度。
- **低延迟**：后端转换流程经过优化（流式读取、临时目录处理与并发友好设计），单个中等大小 Markdown 文件（含图片与公式）常见转换延迟在数百毫秒到数秒级，适合交互式编辑—实时预览场景。

## 解决痛点（详细）

- **表格合并与结构不一致**：自动解析 HTML 风格表格并通过网格填充方式处理 `rowspan`/`colspan`，避免合并单元格导致的数据错位。
- **公式可编辑性差**：与多数方案把公式渲染为图片不同，本项目将 LaTeX→MathML→OMML，输出为 Word 原生公式，兼顾显示与后续编辑。
- **图片资源断链**：支持 ZIP 包上传，自动解包并修正相对路径，保证图像能正确打包进 DOCX。
- **部署与依赖复杂**：通过 Docker+Compose 提供一键部署体验，屏蔽底层环境差异。

## 使用技术（更明确）

- **后端核心**：FastAPI（异步 IO、高并发）、Python 3.12+
- **文档引擎**：python-docx（DOCX 写入与样式控制）
- **解析层**：markdown-it-py（兼容 CommonMark、插件拓展）
- **公式处理**：latex2mathml → lxml → 自有 MathML→OMML 转换器（保证 Word 原生公式）
- **富文本/HTML 支持**：lxml/html5lib（安全解析）、docx-preview（前端 DOCX 预览，用于快速检查）
- **静态前端**：现代 Vanilla JS + docx-preview（VolodymyrBaydalka/docxjs）用于客户端渲染 DOCX 预览
- **部署/容器**：Docker / Docker Compose（快速、一致的运行环境）

## 使用场景与适用性

- 需要高保真公式、可编辑 Word 输出的学术、教育文档导出；
- 需要把复杂 Markdown（表格、多图片、代码、公式）批量或交互式转为 DOCX 的业务场景；
- 文档预览要求低延迟、可交互编辑与快速下载的在线文档转换服务。

---

以上内容已补充“解决痛点”“使用技术”并强调了输出效果好与低延迟特性。如需我把 README 转为项目主页或增加快速对比示例（与其他转换器的对比截图/性能表），我可以继续补充。