# docx_to_markdown

**Repository Path**: michah/docx_to_markdown

## Basic Information

- **Project Name**: docx_to_markdown
- **Description**: 基于 Flask 的后端服务与轻量前端页面，实现将 `.docx`（Word）文档转换为 Markdown 文本并提取图片，支持在线预览与将 Markdown + 图片打包下载。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## Python 使用 Flask 将 DOCX 转为 Markdown（支持图片提取一键下载）

### 摘要

- 本文演示一个基于 Flask 的后端 + 简单前端页面的项目，能够将上传的 `.docx` 文件转换为 Markdown，并提取图片以供下载/预览。
- 包含运行方式、关键代码解析（`app.py`）、前端 `templates/index.html` 功能说明，以及常见注意事项。

### 目录

- 项目简介
- 环境与依赖
- 项目结构
- 运行步骤
- `app.py` 关键代码解析
- 前端 `templates/index.html` 功能概览
- 常见问题与注意事项
- 总结

### 项目简介

- 功能：上传 `.docx` → 返回 Markdown 文本 + 提取图片（通过 API 提供图片访问 URL），前端支持预览与打包下载 ZIP。
- 适用场景：将 Word 文档内容迁移到博客、技术文档、知识库时快速生成 Markdown。

### 环境与依赖

- Python 3.8+（示例中也可用 Python 3.13）
- 依赖见 `requirements.txt`：

```text
python-docx==0.8.11
Flask==2.3.0
Flask-CORS==4.0.0
Werkzeug==2.3.0
```

- 安装命令：

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 项目结构（简要）

- `app.py` — Flask 后端，负责接收上传、解析 DOCX、提取图片并返回 Markdown。
- `templates/index.html` — 前端页面，基于 Vue 3，提供上传、展示与下载功能。
- `uploads/` — 存放上传的文件与提取的图片（运行时生成）。

### 运行步骤

- 启动服务：

```bash
python app.py
# 或
python3 app.py
```
![alt text](docs/image-1.png)
![alt text](docs/image.png)
- 服务默认监听 `0.0.0.0:5000`，打开浏览器访问 `http://localhost:5000/` 使用前端页面。

### `app.py` 关键代码解析

- 应用与配置
  - 创建 Flask 实例：`app = Flask(__name__, static_folder='templates', static_url_path='')`
  - 配置上传目录与最大文件大小：`UPLOAD_FOLDER = 'uploads'`、`MAX_FILE_SIZE = 50 * 1024 * 1024`
- 允许的文件检查
  - `allowed_file(filename)`：只允许 `docx`/`doc` 扩展名。
- 图片提取：`extract_images_from_run(run, image_dir, image_counter, doc_part=None)`
  - 通过读取 run 元素的 drawing/blip，使用关系 id（embed）找到 `image_part`，读取其 `blob` 保存为文件；根据 `content_type` 推断扩展名。
- DOCX 转 Markdown：`convert_docx_to_markdown(docx_path, image_dir=None)`
  - 使用 `python-docx` 的 `Document(docx_path)` 加载文档。
  - 遍历 `doc.paragraphs`：对每个 run 提取图片、根据段落样式（如 `Heading 1`）生成对应 Markdown 标题，非标题段落调用 `process_runs` 处理加粗/斜体/下划线等；遍历 `doc.tables` 使用 `convert_table_to_markdown` 转换表格。
- 文本样式处理：`process_runs(runs)`
  - 根据 `run.bold`、`run.italic`、`run.underline` 包裹 `**`、`*`、`__`，然后拼接返回。
- 表格转换：`convert_table_to_markdown(table, image_dir, image_counter)`
  - 逐行逐单元格处理，单元格内可能包含图片（同样提取），生成 Markdown 表格和表头分隔符。
- API 路由
  - `GET /`：返回前端页面 `templates/index.html`。
  - `GET /api/health`：健康检查，返回 `{'status': 'ok'}`。
  - `POST /api/convert`：接收上传文件（字段 `file`），保存文件、创建图片目录 `{stem}_images`、调用转换并返回 JSON（包含 `markdown`、`images` 列表和 `image_count`）。
  - `GET /api/image/<path:filepath>`：从 `uploads/` 安全返回图片文件（带路径校验）。

### 前端 `templates/index.html` 功能概览

- 基于 Vue 3（CDN）实现，交互包括：
  - 拖拽或点击上传 `.docx` 文件（前端做扩展名校验）。
  - 显示已选文件名和大小，调用 `/api/convert` 上传文件并等待结果；期间显示 Loading 状态。
  - 转换成功后弹窗显示 Markdown 内容、预览（简单解析）和图片列表。
  - 支持将 Markdown + 图片打包为 ZIP 下载（使用 JSZip）。
- 前端渲染要点：
  - `renderMarkdown`：简单将 Markdown → HTML（支持标题、加粗、斜体、代码块、图片、链接、列表的基础转换），并把图片路径替换为后端返回的 `img.path`。
  - 下载逻辑：先把 `document.md` 写入 zip，再 fetch 每个图片的 URL 把 Blob 写入 zip，最后触发浏览器下载。

### 示例：用 curl 调用 API

```bash
curl -F "file=@/path/to/test.docx" http://localhost:5000/api/convert
```

响应后可直接访问图片：

```
http://localhost:5000/api/image/<yourfile_stem>_images/image_1.png
```
Gitee: [https://gitee.com/michah/docx_to_markdown](https://gitee.com/michah/docx_to_markdown)
GitHub: [https://github.com/mlb0925/docx_to_markdown](https://github.com/mlb0925/docx_to_markdown)