Feature Request: Save embedded images from PDFs as separate files with relative Markdown links

[agodianel]

Problem

When converting PDFs with embedded images to Markdown, markitdown currently either:

• Truncates base64 data (showing ![](data:image/png;base64...)), or
• Preserves full base64 inline (which makes the Markdown file very large and unsuitable for RAG/indexing)

For full-context RAG pipelines and document archival, I need:

1. Embedded images extracted and saved as separate files (e.g. images/page3-figure1.png)
2. Markdown references using relative paths: ![description](images/page3-figure1.png)
3. Optional: image metadata/captions in front matter or inline comments

Use case

• Converting technical documentation, datasheets, and PDFs with diagrams for AI/LLM ingestion
• Preserving full document context including visual information
• Keeping Markdown files lightweight and portable while still referencing images

Proposed behavior

Add a CLI flag and Python API option, for example:

markitdown document.pdf --extract-images --output-dir ./output

from markitdown import MarkItDown
md = MarkItDown(extract_images=True, output_dir="./output")
result = md.convert("document.pdf")
# result.markdown includes: 
# Actual image files saved to ./output/images/

Alternatives considered

• Full base64 inline: makes files too large for indexing/LLM pipelines
• Image descriptions only: loses visual context for diagrams, charts, schematics
• Manual extraction: error-prone and not reproducible

Additional context

• Related to issue how to save image in the markdown #162 (closed) and PR Add support for preserving base64 encoded images #1140 (base64 preservation added)
• Complements issue Describing Images Inline in PDFs for Better RAG #1346 (LLM image descriptions for RAG)
• Would benefit users working with schematics, datasheets, research papers, and technical documentation

Environment

• markitdown version: 0.1.6
• Python version: 3.11+
• OS: macOS

[Imposter069]

I strongly support this feature request.

For RAG pipelines, technical documentation, research papers, and datasheet processing, embedding images as base64 inside Markdown creates significant challenges. Large base64 strings increase file size, make indexing less efficient, and can unnecessarily consume context window space when documents are processed by LLMs.

Saving embedded images as separate files and referencing them through relative Markdown links would provide several benefits:

• Keeps Markdown files lightweight and portable
• Preserves original visual context (diagrams, charts, schematics, screenshots)
• Improves compatibility with RAG and vector database ingestion workflows
• Makes document versioning and storage more efficient
• Enables reproducible document conversion without manual image extraction

An example output structure could be:

output/
├── document.md
└── images/
    ├── page1-image1.png
    ├── page3-figure1.png
    └── page5-chart2.png

And the generated Markdown:

![Figure 1](images/page3-figure1.png)

It would also be useful if image filenames could include page numbers or figure identifiers where available. Optional support for captions and image metadata would further improve downstream processing for AI and search applications.

This feature would complement existing base64-preservation functionality while providing a much more practical workflow for users working with large document collections and LLM-based systems.