# md2docx-py-project

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

## Basic Information

- **Project Name**: md2docx-py-project
- **Description**: 功能概览：（1）- 支持输入：md;docx;html;（2）- 支持输出：md;docx;html;pdf；（3）- 可互转：md;docx;html; 优点：（1）非ocr-无gpl；（2）速度快；效果好；(3)要求latex公式转为word框-MathML形式;其他：；（4）支持插入图片；（5）内存占用:70M；缺点：（1）docx预览与保存一致性问题；
- **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-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MD to DOCX Converter

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

## 总体设计
以md的zip为中间文件类型进行预览和转换；

## 技术原理
- 前端预览：前端预览面板使用 marked.js 解析 Markdown，并使用 KaTeX 对公式块进行网页级渲染。

## 功能概览
- 支持输入：md;docx;html;pdf;
- 支持输出：md;docx;html;pdf；
- 可双向互转：md;docx;html;
- 支持单向导入：pdf -> md/docx/pdf;

## 核心设计与优势

- **⚡ 零延迟实时渲染预览**：前端引入 Marked.js + KaTeX 引擎，通过沙箱化 `<iframe>` 和独创的“数学公式提取保护”占位机制，实现 **<50ms 的超高速本地实时预览**。编辑体验丝滑无阻碍。
- **📥 后台静默保存同步**：前端打字后后台静默触发 **1.2 秒的 debounced 保存**，在服务器生成 Word 文档，确保“下载 DOCX”按钮所下载的文件永远是最新版本。
- **Word 原生 OMML 数学公式**：LaTeX 数学公式（包括 `\xrightarrow{\text{...}}` 箭头公式）全部转换为 Word 原生的 OMML `<m:limUpp>`（上极限结构）公式，而非文本拼凑或图片，保证公式在导出的 DOCX 中是可直接编辑、排版的原生 Word 公式。
- **标题样式智能剥离**：彻底解决 Markdown 标题中包含双星号（例如 `# **一、 标题**`）导致导出 DOCX 中残留 `**` 字符的 Bug，自动剥离格式字符并正确编译为 DOCX 原生的加粗标题运行（runs）。

## 页面样式

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

### 转换效果-复杂公式下
![2](./images/2.png)

## 优点
- **无标点合并**：会将文件名保存中不支持的符号如 `\ / : * ? " < > |` 自动替换为 `-`。
- 图片支持url直链；
-内存占用小：58M；
- 对齐样式保留；
- **智能脚注显示**：通过预扫描定位脚注定义，智能切换标准脚注引用与 HTML 上标标签。如 `^[18]`。

## 缺点：
- docx预览和保存文件不一致问题：打开的docx和预览的docx每页的开始和结束位置应一致 - 无法解决


## 特点
- **不保留分栏结构**：PDF 导入不保留双分栏或多栏等复杂版面，统一转换为单栏流式版面，便于二次编辑与重新排版；

## 快速启动

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

## 功能特性

- **PDF 本地直接导入**：无需调用外部云端服务，在本地利用 `pdfplumber` 与 `pypdfium2` 快速将 PDF 转换为 Markdown 并提取高精度图片。
  - **段落排版隔离**：自动在提取出的图片、表格和普通文本之间插入双换行符 `\n\n` 进行物理隔离，防止生成 Word 时居中样式向后污染普通段落。
  - **英文两端对齐**：导出的 Word 文档对常规文本段落（特别是英文）默认应用两端对齐（Justify）格式。
  - **拼行与去除连字符**：智能拼接 PDF 文本中的换行折行，自动清除行尾的英文连字符 `-`，合并中文字符间的异常换行与空格。
- **Markdown 解析**：支持标题、列表、表格（标准及合并单元格表格）。【表格合并单元格-复制为相同内容】
- **ZIP 支持**：自动解压并识别包含图片的压缩包，解决相对路径引用问题。
- **LaTeX 公式**：将 LaTeX 转换为 Word 原生 OMML 公式，确保公式可编辑且排版精确。【word公式工具显示】
  - **智能行内公式解析**：支持段落内 `$$` 双美元符行内公式，自动消除解析过程中多余的首尾 `$` 字符残留。
  - **原生拉伸箭头公式**：`\xrightarrow{\text{...}}` 箭头公式会被正确转换为 Word 原生 `<m:limUpp>` 公式，在导出的 DOCX 中能正确拉伸且支持直接编辑。
  - **精确文本样式**：`mtext` / `ms` 标签映射为 Word `<m:nor/>` 正文样式（直立非斜体），`mi` / `mn` / `mo` 保留数学斜体；`mstyle` / `mpadded` 透明传递，`mspace` 静默忽略。
- **图片自适应**：支持 HTML 样式的图片标签，可控对齐方式及 `width` 展示比例。【图片可以插入进入docx】
- **实时极速预览**：编辑器输入后通过 Marked + KaTeX 瞬间（<20ms）热重载并同步至前端 `iframe` 视图，兼顾完美显示与极致的低延迟体验。
- **现代 UI**：极致视觉享受，基于 Catppuccin 风格玻璃拟态设计的响应式 Web 界面。

## 注意
- **脚注显示**：如果文中出现了 `[^18]`，但在文档的任何地方都找不到对应的脚注定义（比如在文档末尾写着 `[^18]: 这是一个脚注`），解析器就会认为这只是一个普通的文本符号，而不是脚注。

## 效果与可编辑性

- **渲染效果优秀**：将 LaTeX 转换为 Word 原生 OMML 公式（而非图片），在 Word 中可直接编辑、复制与再次排版，保证输出文档的可维护性与美观度。
- **零延迟写作**：完全消除了在键盘输入时等待服务器后台 LibreOffice/PDF.js 渲染 of a few seconds 的卡顿，彻底实现所见即所得。

## 解决痛点

- **打字卡顿与预览延迟**：原有 PDF.js 方案依靠后端 LibreOffice headless 导出，导致实时预览有 2-3 秒的停顿。现在前端采用沙箱 Marked + KaTeX 解析，将打字预览延迟降低到几乎为 0。
- **标题粗体星号残留**：修复了 headings 导出时无法二次解析行内标记的问题，让双星号标题在 Word 导出的文档里完美呈现为原生加粗样式。
- **表格合并与结构不一致**：自动解析 HTML 风格表格并通过网格填充方式处理 `rowspan`/`colspan`，避免合并单元格导致的数据错位。
- **公式可编辑性差**：与多数方案把公式渲染为图片不同，本项目将 LaTeX→MathML→OMML，输出为 Word 原生公式，兼顾显示与后续编辑。
- **图片资源断链**：支持 ZIP 包上传，自动解包并修正相对路径，保证图像能正确打包进 DOCX。
- **标题蓝色字体问题**：将导出的 Word 文档 Heading 标题样式默认字体颜色统一设定为纯黑色，解决由微软默认样式导致的导出 PDF 标题呈现为蓝色的问题。
- 有上标无下标的不要显示下标的框（基于libreoffice也实现了）；

## 转换技术架构与原理

本项目在各格式互转过程中，**完全未使用**像 `Pandoc` 或 `Chrome (Puppeteer/Selenium)` 这种庞大且高开销的外部工具，以确保系统轻量、资源占用低、启动速度快。以下是具体格式转换的技术架构说明：

| 转换方向 | 核心使用技术/库 | 实现原理与技术细节 |
| :--- | :--- | :--- |
| **PDF → MD** | `pdfplumber`<br>`pypdfium2`<br>`pdf2docx`（内部模块） | 1. 采用 `pdfplumber` 提取文本、表格和结构化布局；<br>2. 结合 `pypdfium2` 和 `pdf2docx` 提取高清晰度图片；<br>3. 采用流式物理隔离排版，自动将图片、表格与普通文本段落使用双换行符（`\n\n`）物理隔离，防止样式串扰；<br>4. 自动清除末尾连字符（Hyphen）并智能拼接折行，对英文段落应用两端对齐，防止图下段落误居中。 |
| **MD → DOCX** | `markdown-it-py`<br>`python-docx`<br>`latex2mathml` | 1. 使用 `markdown-it-py` 精确解析 Markdown 生成抽象语法树（AST）；<br>2. 后端基于 `python-docx` 逐个 Token 构建 Word 段落和文本 Runs 样式；<br>3. 对于 LaTeX 公式，利用 `latex2mathml` 转为 MathML，再通过专有的 XML 转换器映射为 Word 原生 **OMML 数学公式**，公式在 Word 中 100% 可直接编辑。 |
| **DOCX → MD** | `mammoth`<br>`lxml_html_clean`<br>`markdownify` | 1. 采用 `mammoth` 将 DOCX 解析为干净的语义化 HTML，并提取内嵌图片到磁盘；<br>2. 用 `lxml_html_clean` 进行内容净化过滤；<br>3. 利用 `markdownify` 将 HTML 标签逆向编译为标准 Markdown 文本，并保持相对路径图片引用。 |
| **MD → HTML** | `Marked.js`<br>`KaTeX.js` | 1. **前端浏览器本地直接解析**。使用 `Marked.js` 解析 MD 结构，`KaTeX` 极速渲染 LaTeX 公式；<br>2. 本地直接在沙箱 `<iframe>` 内完成热重载（时间 <50ms），实现真正的**打字零卡顿实时预览**。 |
| **DOCX → PDF** | `LibreOffice Headless` | 1. 临时生成排除了 LibreOffice 渲染缺陷（如数学公式空基底方框、特定 Emoji 重叠与乱码）的临时 DOCX 副本（例如将 `✅` 转换为高兼容性的 `✔`，并设置文档默认 CJK 字体映射）；<br>2. 调用容器中的 LibreOffice 命令行进行静默无头（Headless）转换，输出 PDF；<br>3. 自动回收并清理临时 DOCX 副本。 |

---

## 使用技术

- **后端核心**：FastAPI（异步 IO、高并发）、Python 3.12+
- **文档引擎**：python-docx（DOCX 写入与样式控制）
- **解析层**：markdown-it-py（兼容 CommonMark、插件拓展）
- **公式处理**：latex2mathml → lxml → 自有 MathML→OMML 转换器（保证 Word 原生公式）
- **静态前端**：现代 Vanilla JS + Marked.js + KaTeX.js（通过 CDN 加载，实现零开销极速沙箱预览）
- **部署/容器**：Docker / Docker Compose