docs/version3.x/doc2md.md
文档转 Markdown（doc2md）是 PaddleOCR 内置的轻量级 Office 文档结构化转换功能，无需 OCR 推理，直接解析文档结构并输出规范的 Markdown 文本。适用于需要将 Word、Excel、PowerPoint 文件快速转为可读文本的场景，如知识库构建、文档检索、内容提取等。
支持格式：.docx（Word）/ .xlsx（Excel）/ .pptx（PowerPoint）
核心能力一览：
<table> <thead> <tr> <th>功能</th> <th>Word (.docx)</th> <th>Excel (.xlsx)</th> <th>PowerPoint (.pptx)</th> </tr> </thead> <tbody> <tr> <td>标题层级</td> <td>✅ 内置样式 + 字号启发式 + 中文编号</td> <td>— </td> <td>— </td> </tr> <tr> <td>文本格式化（粗体/斜体/下划线/删除线）</td> <td>✅</td> <td>✅</td> <td>✅</td> </tr> <tr> <td>上标 / 下标</td> <td>✅</td> <td>✅</td> <td>✅</td> </tr> <tr> <td>超链接</td> <td>✅</td> <td>✅</td> <td>✅</td> </tr> <tr> <td>列表（有序 / 无序 / 嵌套）</td> <td>✅</td> <td>— </td> <td>— </td> </tr> <tr> <td>表格（含合并单元格）</td> <td>✅ HTML table</td> <td>✅ HTML table</td> <td>✅ HTML table</td> </tr> <tr> <td>图片</td> <td>✅ 按比例宽度</td> <td>✅ 浮动图片</td> <td>✅ 按比例宽度</td> </tr> <tr> <td>数学公式（OMML → LaTeX）</td> <td>✅ 行内 / 显示公式</td> <td>✅ drawing 层公式</td> <td>✅</td> </tr> <tr> <td>代码块</td> <td>✅ 等宽字体自动识别</td> <td>— </td> <td>— </td> </tr> <tr> <td>文本框</td> <td>✅</td> <td>— </td> <td>— </td> </tr> <tr> <td>图表（Chart）</td> <td>✅ → HTML table</td> <td>— </td> <td>✅ 14 种图表类型</td> </tr> <tr> <td>页眉 / 页脚</td> <td>✅ 多节 + 奇偶页</td> <td>— </td> <td>— </td> </tr> <tr> <td>多 sheet / 多幻灯片</td> <td>— </td> <td>✅</td> <td>✅ <code>---</code> 分隔</td> </tr> <tr> <td>演讲者备注</td> <td>— </td> <td>— </td> <td>✅</td> </tr> </tbody> </table>在使用 doc2md 功能前，请确保已按照安装教程完成 PaddleOCR 基础安装，然后安装 doc2md 可选依赖：
pip install "paddleocr[doc2md]"
依赖说明：
<table> <thead> <tr> <th>包名</th> <th>版本约束</th> <th>用途</th> </tr> </thead> <tbody> <tr> <td><code>python-docx</code></td> <td><code>>=0.8.11</code></td> <td>Word (.docx) 文档解析</td> </tr> <tr> <td><code>python-pptx</code></td> <td><code>>=0.6.21</code></td> <td>PowerPoint (.pptx) 文档解析</td> </tr> <tr> <td><code>openpyxl</code></td> <td><code>>=3.0.0</code></td> <td>Excel (.xlsx) 文档解析</td> </tr> <tr> <td><code>pylatexenc</code></td> <td><code>>=2.10,<3</code></td> <td>数学公式 Unicode → LaTeX 符号映射</td> </tr> </tbody> </table># 转换 Word 文档，输出到文件
paddleocr doc2md -i report.docx -o output.md
# 转换 Excel 表格，输出到文件
paddleocr doc2md -i data.xlsx -o output.md
# 转换 PowerPoint 演示文稿，输出到文件
paddleocr doc2md -i slides.pptx -o output.md
# 不指定输出路径，结果打印到终端
paddleocr doc2md -i report.docx
# 查看支持的格式列表
paddleocr doc2md --formats
<b>说明：</b>支持 <code>.docx</code>、<code>.xlsx</code>、<code>.pptx</code> 格式。</td>
<td><code>str</code></td> <td>必填</td> </tr> <tr> <td><code>-o</code>, <code>--output</code></td> <td><b>含义：</b>输出 Markdown 文件路径。<b>说明：</b>如果不设置，转换结果将打印到标准输出（stdout）。设置后，Markdown 写入指定文件，图片保存到同目录下的 <code>images/</code> 文件夹。</td>
<td><code>str</code></td> <td><code>None</code></td> </tr> <tr> <td><code>-q</code>, <code>--quiet</code></td> <td><b>含义：</b>静默模式。<b>说明：</b>启用后不打印耗时、保存路径等提示信息。</td>
<td>flag</td> <td><code>False</code></td> </tr> <tr> <td><code>--formats</code></td> <td><b>含义：</b>列出当前支持的文件格式后退出。<b>说明：</b>启用后不需要 <code>--input</code>，仅输出支持的扩展名列表。</td>
<td>flag</td> <td><code>False</code></td> </tr> <tr> <td><code>--no-drawings</code></td> <td><b>含义：</b>跳过文本框和 drawing 层内容提取。<b>说明：</b>适用于 <code>.docx</code> 和 <code>.xlsx</code>，启用后将跳过文本框（docx）和 drawing 层数学公式（xlsx）的提取。</td>
<td>flag</td> <td><code>False</code></td> </tr> <tr> <td><code>--no-headers-footers</code></td> <td><b>含义：</b>跳过页眉页脚内容提取。<b>说明：</b>仅适用于 <code>.docx</code>，启用后不提取文档的页眉和页脚内容。</td>
<td>flag</td> <td><code>False</code></td> </tr> <tr> <td><code>--sheet-name</code></td> <td><b>含义：</b>仅转换指定名称的 sheet。<b>说明：</b>仅适用于 <code>.xlsx</code>，不设置则转换所有 sheet。</td>
<td><code>str</code></td> <td><code>None</code></td> </tr> <tr> <td><code>--max-rows</code></td> <td><b>含义：</b>每个 sheet 的最大转换行数。<b>说明：</b>仅适用于 <code>.xlsx</code>，用于限制大表格的输出行数。</td>
<td><code>int</code></td> <td><code>None</code></td> </tr> </tbody> </table> </details>基础用法：
from paddleocr._doc2md import convert
# 转换文档，返回结果对象
result = convert("report.docx")
# 访问 Markdown 文本
print(result.markdown)
# 查看提取的图片（字典，key 为相对路径，value 为图片字节）
print(list(result.images.keys()))
# 查看文档标题
print(result.title)
# 查看元信息（格式、sheet 数等）
print(result.metadata)
ConvertResult 字段说明：
指定输出路径（自动保存文件和图片）：
from paddleocr._doc2md import convert
# 指定 output 后，Markdown 写入文件，图片保存到同目录 images/ 下
result = convert("report.docx", output="output/report.md")
各格式可用的 kwargs 参数：
<table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>适用格式</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>extract_drawings</code></td> <td><code>bool</code></td> <td><code>True</code></td> <td>docx, xlsx</td> <td>是否提取文本框（docx）/ drawing 层数学公式（xlsx）</td> </tr> <tr> <td><code>extract_headers_footers</code></td> <td><code>bool</code></td> <td><code>True</code></td> <td>docx</td> <td>是否提取页眉页脚</td> </tr> <tr> <td><code>sheet_name</code></td> <td><code>Optional[str]</code></td> <td><code>None</code></td> <td>xlsx</td> <td>仅转换指定名称的 sheet，<code>None</code> 表示转换全部</td> </tr> <tr> <td><code>max_rows</code></td> <td><code>Optional[int]</code></td> <td><code>None</code></td> <td>xlsx</td> <td>每个 sheet 的最大转换行数</td> </tr> </tbody> </table>按格式传入 kwargs 示例：
from paddleocr._doc2md import convert
# Word：不提取文本框和页眉页脚
result = convert("report.docx", extract_drawings=False, extract_headers_footers=False)
# Excel：仅转换名为 "Sheet1" 的 sheet，最多 100 行
result = convert("data.xlsx", sheet_name="Sheet1", max_rows=100)
标题识别支持三种方式：
#–######文本格式化：粗体（**）、斜体（*）、下划线（<u>）、删除线（~~）、上标（<sup>）、下标（<sub>）
列表：有序列表、无序列表、嵌套列表，自动识别缩进层级
表格：输出为 HTML <table> 格式，支持 rowspan/colspan 合并单元格
图片：按文档内容区宽度百分比计算，输出 `` 形式
数学公式：OMML 格式公式转为 LaTeX，行内公式为 $...$，显示公式为 $$...$$
代码块：自动检测等宽字体（Courier New、Consolas 等 9 种字体），输出为 fenced code block（```）
其他：文本框内容（wps:txbx）、图表（Chart → HTML table）、超链接（两种格式）、页眉页脚（多节 + 奇偶页）
多 sheet：每个 sheet 输出一个以 ## sheet名称 开头的章节
数据边界裁剪：自动去除尾部空行和空列，只输出有效数据区域
合并单元格：使用 rowspan/colspan 还原单元格合并结构
字体格式化：粗体、斜体、下划线、删除线、上标、下标
超链接：支持单元格级超链接
浮动图片：支持 OneCellAnchor 和 TwoCellAnchor 两种锚定方式的浮动图片
数学公式：通过解析 drawing 层 XML 提取 OMML 格式公式并转为 LaTeX
多幻灯片：每张幻灯片内容以 --- 分隔
文本格式化：粗体、斜体、下划线、删除线、上标、下标
图片：按幻灯片宽度百分比计算，输出带宽度的 `` 标签
表格：HTML <table> 格式，支持合并单元格，支持带背景图片的表格
图表：支持 14 种图表类型，转换为 HTML table 输出
分组形状（GroupShape）：递归处理嵌套的形状组合
数学公式：从 mc:AlternateContent 中提取 OMML 格式公式并转为 LaTeX
演讲者备注：附加在每张幻灯片内容末尾
Q：转换时提示 RuntimeError: python-docx is required？
doc2md 采用延迟导入，缺少对应格式的解析库时会抛出此错误。请根据提示安装对应依赖：
pip install python-docx # Word (.docx)
pip install python-pptx # PowerPoint (.pptx)
pip install openpyxl # Excel (.xlsx)
pip install pylatexenc # 数学公式支持
或直接安装全部依赖：pip install "paddleocr[doc2md]"
Q：格式不支持，提示 ValueError？
运行 paddleocr doc2md --formats 查看当前支持的扩展名。doc2md 仅支持 .docx、.xlsx、.pptx，不支持 .doc（旧版 Word）、.csv、.pdf 等格式。
Q：Excel 转换后表格行数很多，输出太长？
使用 --max-rows 限制每个 sheet 的行数：
paddleocr doc2md -i data.xlsx -o output.md --max-rows 100
Q：只想转换 Excel 中的某一个 sheet？
使用 --sheet-name 指定 sheet 名称：
paddleocr doc2md -i data.xlsx -o output.md --sheet-name "Sheet1"
Q：Word 文档中的页眉页脚内容不需要，如何跳过？
使用 --no-headers-footers 参数：
paddleocr doc2md -i report.docx -o output.md --no-headers-footers
Q：图片输出到哪里？
使用 -o 指定输出文件时，图片自动保存在输出文件同目录的 images/ 文件夹下。Markdown 文件中的图片引用路径也会相应更新为相对路径。
Q：doc2md 与 PaddleOCR 的 OCR 功能有什么区别？
doc2md 直接解析 Office 文档的 XML 结构，不使用任何 OCR 模型，速度快、零 GPU 依赖。适用于有原始 Office 文件的场景。PaddleOCR 的 OCR 功能则针对图片或扫描件进行文字识别，适用于没有原始文档的场景。