TL;DR
Getting a PDF into Markdown is easy until you hit an image. Doing this well requires solving three specific problems: pulling images out intelligently without grabbing background junk, storing them with sensible local file paths, and figuring out which caption goes with which image. By leveraging advanced AI vision models and packing the output into a structured ZIP file, we can create a drop-in ready experience—especially for Obsidian users.
The Problem with PDFs
We all like Markdown because it's just raw text. It plays nice with Git, it's easy to read, and you can dump it into almost any static site generator or knowledge base (like Notion or Obsidian). But a huge chunk of the world's documentation is still stuck in PDFs.
If you just need the text, a basic script can rip it out. The headache starts when the document has charts, diagrams, or photos.
A decent conversion isn't just about scraping. The tool has to figure out where the images actually are, pull them out without ruining the quality, link them correctly in the new .md file, and try not to lose the captions along the way. I'm going to walk through how we tackle these three stages.
What makes a good conversion?
A solid PDF to Markdown with Images setup does more than just copy-paste text. It detects raster images (JPEGs, PNGs) and vector graphics, rips them out to a separate folder, and rebuilds the layout using .
Why bother getting this right?
- Missing context: In a technical spec or a whitepaper, a diagram usually explains the concept better than the paragraphs around it. Lose the image, and the text becomes useless.
- Migration pain: Nobody wants to manually screenshot and paste 50 images when moving a wiki to a new platform.
- Offline support (Obsidian Vaults): To make a localized knowledge base work perfectly in tools like Obsidian, you need physical image files sitting right next to your Markdown file, linked via clean relative paths.
The Hard Parts (and How We Solve Them)
Part 1: Ripping the Images Out
PDFs don't have <img src="..."> tags. What looks like a single picture might be a compressed data block, or worse, fifty different vector paths layered on top of each other.
Where it fails:
- Junk graphics: Most PDFs are full of formatting artifacts—tiny spacing blocks, background watermarks, or decorative lines. You don't want a folder full of
line_01.png. - Vectors: Traditional extraction tools usually only look for bitmaps. If a chart was drawn using native PDF instructions, the tool skips it entirely causing you to lose data.
How we fix it:
- AI-Powered Vision Models: Under the hood, we rely on advanced AI-driven vision models. Instead of digging through a broken PDF structure tree, the model visually analyzes the page like a human would. It draws bounding boxes around actual charts, rasterizes complex vectors natively, and drops the useless decorative junk.
- Immediate processing: The second those images are identified, they are fetched and processed in isolated memory before being converted into standard web formats, ensuring that your data isn't permanently stored anywhere.
Part 2: Managing File Paths for Obsidian
Once you have a folder full of images, you need to point the Markdown file to them without creating a mess.
Where it fails:
- Dumping everything in root: If your script spits out
image_8fA2b.pnginto the same folder as all your markdown files, your vault is going to become unreadable very fast. - Absolute URLs: If a tool hardcodes
https://...for every image, you completely lose the ability to view your notes offline.
How we fix it (The ZIP Export): Our pipeline is built specifically with local-first setups like Obsidian in mind.
- Relative asset rewriting: Before we finalize the Markdown, we run a pass over the entire document to rewrite all image URLs. We convert every source link into a clean, relative path:
. - The "Drop-In" ZIP Archive: We don't just give you a text file. We generate a complete ZIP archive on the fly that contains your final
output.mdalongside anassets/subfolder packed with all your localized images.
For an Obsidian user, this is magic. You download the ZIP, extract it directly into your vault, and your markdown instantly renders every image locally. No broken links, no internet required.
Part 3: Fixing Captions
This is notoriously difficult. A chart is usually useless without its caption (e.g., "Figure 4: Auth Flow"), but in a PDF, that text is just another floating text box.
Where it fails:
- Machines have no idea if a block of text belongs to the image above it, below it, or in the sidebar next to it.
- If you miss the caption, you end up generating empty
tags.
How to fix it:
- Let the AI read the context: Because we leverage advanced layout engines, the system checks the physical whitespace between text blocks and images, combining that with semantic understanding to match up captions like "Table 2.1".
- Double format it: When we find the caption, we inject it directly into the Markdown syntax as Alt Text for SEO and accessibility, allowing your markdown reader to display the text natively without guessing.
Wrapping Up
Building a reliable PDF to Markdown with Images pipeline means fighting the PDF file format at every step. You have to filter out garbage images, manage paths so your repository doesn't become a swamp, and run layout analysis to save the captions.
By combining an advanced AI vision model with a localized assets/ ZIP export, we ensure you spend less time fixing broken links and more time actually building your knowledge base.
FAQ
Why do some pdf extractors output black boxes instead of my images?
Usually, the PDF publisher used a weird color space (like CMYK) or an old compression algorithm like JBIG2. If the tool relies on a basic or outdated decoder, it panics and outputs garbage. You're better off using an AI-backed pipeline.
Why does this tool download a ZIP instead of just text?
To prevent link rot and support tools like Obsidian! By packing your output.md and an assets/ folder together, every image works entirely offline.