paddlepaddle--paddleocr/docs/version3.x/doc2md.en.md

comments

comments
true

Document to Markdown Tutorial

1. Introduction

Document to Markdown (doc2md) is a lightweight Office document conversion feature built into PaddleOCR. It requires no OCR inference — it directly parses document structure and outputs well-formed Markdown text. It is well-suited for scenarios where Word, Excel, or PowerPoint files need to be quickly converted to readable text, such as knowledge base construction, document retrieval, and content extraction.

Supported formats: .docx (Word) / .xlsx (Excel) / .pptx (PowerPoint)

Feature overview:

Feature	Word (.docx)	Excel (.xlsx)	PowerPoint (.pptx)
Heading levels	✅ Built-in styles + font-size heuristic + Chinese numbering	—	—
Text formatting (bold / italic / underline / strikethrough)	✅	✅	✅
Superscript / subscript	✅	✅	✅
Hyperlinks	✅	✅	✅
Lists (ordered / unordered / nested)	✅	—	—
Tables (with merged cells)	✅ HTML table	✅ HTML table	✅ HTML table
Images	✅ Proportional width	✅ Floating images	✅ Proportional width
Math formulas (OMML → LaTeX)	✅ Inline / display formulas	✅ Drawing-layer formulas	✅
Code blocks	✅ Monospace font auto-detection	—	—
Text boxes	✅	—	—
Charts	✅ → HTML table	—	✅ 14 chart types
Headers / footers	✅ Multi-section + odd/even pages	—	—
Multiple sheets / slides	—	✅	✅ Separated by ---
Speaker notes	—	—	✅

2. Quick Start

Before using doc2md, make sure you have completed the PaddleOCR base installation as described in the installation guide, then install the doc2md optional dependencies:

pip install "paddleocr[doc2md]"

Dependency details:

Package	Version constraint	Purpose
python-docx	>=0.8.11	Word (.docx) document parsing
python-pptx	>=0.6.21	PowerPoint (.pptx) document parsing
openpyxl	>=3.0.0	Excel (.xlsx) document parsing
pylatexenc	>=2.10,<3	Math formula Unicode → LaTeX symbol mapping

2.1 Command Line

# Convert a Word document to a file
paddleocr doc2md -i report.docx -o output.md

# Convert an Excel spreadsheet to a file
paddleocr doc2md -i data.xlsx -o output.md

# Convert a PowerPoint presentation to a file
paddleocr doc2md -i slides.pptx -o output.md

# Omit output path to print to stdout
paddleocr doc2md -i report.docx

# List supported formats and exit
paddleocr doc2md --formats

Click to expand the full list of command line parameters

Parameter	Description	Type	Default
-i, --input	Meaning: Input file path. Required (may be omitted when --formats is used). Note: Supports .docx, .xlsx, and .pptx formats.	str	required
-o, --output	Meaning: Output Markdown file path. Note: If not set, the result is printed to stdout. When set, Markdown is written to the specified file and images are saved to an images/ subdirectory alongside it.	str	None
-q, --quiet	Meaning: Quiet mode. Note: When enabled, timing and save-path messages are suppressed.	flag	False
--formats	Meaning: Print the list of supported file formats and exit. Note: --input is not required when this flag is used.	flag	False
--no-drawings	Meaning: Skip text box and drawing-layer content extraction. Note: Applies to .docx and .xlsx. When enabled, text boxes (docx) and drawing-layer math formulas (xlsx) are not extracted.	flag	False
--no-headers-footers	Meaning: Skip header and footer extraction. Note: Applies to .docx only.	flag	False
--sheet-name	Meaning: Convert only the sheet with the given name. Note: Applies to .xlsx only. All sheets are converted when not set.	str	None
--max-rows	Meaning: Maximum number of rows to convert per sheet. Note: Applies to .xlsx only. Use this to limit output for large spreadsheets.	int	None

2.2 Python API

Basic usage:

from paddleocr._doc2md import convert

# Convert a document and get the result object
result = convert("report.docx")

# Access the Markdown text
print(result.markdown)

# List extracted images (dict mapping relative path → bytes)
print(list(result.images.keys()))

# Get the document title
print(result.title)

# Get metadata (format, sheet count, etc.)
print(result.metadata)

ConvertResult fields:

Field	Type	Description
markdown	str	The converted Markdown text
images	dict[str, bytes]	Extracted images dict; key is a relative path (e.g. images/image1.png), value is raw bytes
title	Optional[str]	Document title; may be None
metadata	dict	Document metadata such as format type and sheet count

Writing output to a file (images saved automatically):

from paddleocr._doc2md import convert

# When output is specified, Markdown is written to the file
# and images are saved to images/ in the same directory
result = convert("report.docx", output="output/report.md")

Available kwargs by format:

Parameter	Type	Default	Formats	Description
extract_drawings	bool	True	docx, xlsx	Whether to extract text boxes (docx) / drawing-layer math formulas (xlsx)
extract_headers_footers	bool	True	docx	Whether to extract headers and footers
sheet_name	Optional[str]	None	xlsx	Convert only the named sheet; None converts all sheets
max_rows	Optional[int]	None	xlsx	Maximum number of rows to convert per sheet

Passing kwargs by format:

from paddleocr._doc2md import convert

# Word: skip text boxes and headers/footers
result = convert("report.docx", extract_drawings=False, extract_headers_footers=False)

# Excel: convert only "Sheet1", up to 100 rows
result = convert("data.xlsx", sheet_name="Sheet1", max_rows=100)

3. Supported Features by Format

3.1 Word (.docx)

Heading detection uses three strategies:

• Built-in Heading styles: Word's built-in Heading 1–6 styles map directly to #–######
• Font-size heuristic: paragraphs with a font size more than 1.5× the body text and short length are promoted to headings
• Chinese numbering: "一、" patterns are treated as H2; "（一）" patterns as H3

Text formatting: bold (**), italic (*), underline (<u>), strikethrough (~~), superscript (<sup>), subscript (<sub>)

Lists: ordered, unordered, and nested lists; indentation level is detected automatically

Tables: output as HTML <table> with rowspan/colspan for merged cells

Images: width is calculated as a percentage of the content area; output as <img width="75%">

Math formulas: OMML formulas are converted to LaTeX; inline formulas use $...$ and display formulas use $$...$$

Code blocks: monospace fonts (Courier New, Consolas, and 7 others) are detected automatically and output as fenced code blocks (```)

Other: text boxes (wps:txbx), charts (Chart → HTML table), hyperlinks (two formats supported), headers and footers (multi-section + odd/even pages)

3.2 Excel (.xlsx)

Multiple sheets: each sheet is output as a section beginning with ## sheet_name

Data boundary trimming: trailing empty rows and columns are removed; only the effective data range is output

Merged cells: cell merges are reproduced using rowspan/colspan

Text formatting: bold, italic, underline, strikethrough, superscript, subscript

Hyperlinks: cell-level hyperlinks are supported

Floating images: both OneCellAnchor and TwoCellAnchor anchor types are supported

Math formulas: OMML formulas are extracted from the drawing-layer XML and converted to LaTeX

3.3 PowerPoint (.pptx)

Multiple slides: slide content is separated by ---

Text formatting: bold, italic, underline, strikethrough, superscript, subscript

Images: width is calculated as a percentage of the slide width; output as <img> tags with a width attribute

Tables: HTML <table> format with merged cell support; tables with background images are handled

Charts: 14 chart types are supported; all are converted to HTML table output

Group shapes: nested shape groups are processed recursively

Math formulas: OMML formulas are extracted from mc:AlternateContent and converted to LaTeX

Speaker notes: appended at the end of each slide's content

4. FAQ

Q: I get RuntimeError: python-docx is required during conversion.

doc2md uses lazy imports — if a required parsing library is missing, this error is raised. Install the dependency for the format you need:

pip install python-docx     # Word (.docx)
pip install python-pptx     # PowerPoint (.pptx)
pip install openpyxl        # Excel (.xlsx)
pip install pylatexenc      # Math formula support

Or install all dependencies at once: pip install "paddleocr[doc2md]"

---

Q: I get a ValueError saying the format is not supported.

Run paddleocr doc2md --formats to see the currently supported extensions. doc2md only supports .docx, .xlsx, and .pptx. Formats such as .doc (legacy Word), .csv, and .pdf are not supported.

---

Q: The Excel output is very long because the table has too many rows.

Use --max-rows to limit the number of rows per sheet:

paddleocr doc2md -i data.xlsx -o output.md --max-rows 100

---

Q: I only want to convert one specific sheet from an Excel file.

Use --sheet-name to specify the sheet by name:

paddleocr doc2md -i data.xlsx -o output.md --sheet-name "Sheet1"

---

Q: How do I skip headers and footers in a Word document?

Use the --no-headers-footers flag:

paddleocr doc2md -i report.docx -o output.md --no-headers-footers

---

Q: Where are the extracted images saved?

When -o is specified, images are automatically saved to an images/ subdirectory in the same directory as the output file. Image references in the Markdown file use relative paths accordingly.

---

Q: What is the difference between doc2md and PaddleOCR's OCR feature?

doc2md parses the XML structure of Office documents directly — no OCR models are used, making it fast with zero GPU requirement. It is suitable when the original Office file is available. PaddleOCR's OCR feature recognizes text from images or scanned documents, and is suitable when no original document exists.