From docx to Obsidian: getting image paths right
Text converts cleanly between Word and Markdown. Images are where migrations break: the moment a converted file moves into a vault, every screenshot needs to be a real file on disk at a path Obsidian can resolve from that note's location. Settle the image pipeline first and everything else is routine.
This guide covers how pandoc pulls media out of a docx file, what lands on disk, and a repeatable workflow that ends with a working Obsidian note, plus the two classic traps: colliding image names across documents, and Windows vector formats that Obsidian cannot display.
Why images are the hard part
A docx file is a zip archive. The paragraphs live in XML, but every screenshot, chart, and diagram sits in a media folder inside that archive, referenced through internal relationships rather than filesystem paths. Nothing you see in Word corresponds to what a Markdown file needs afterward, so a converter has to rewrite text and unpack binaries at the same time.
Skip the unpacking half and you get a note full of links that point nowhere. Obsidian renders the broken placeholders without complaint, and the damage usually surfaces weeks later, when you open the note on a different device or share the vault with a colleague. Planning the image pipeline before converting is what separates a clean migration from a repair job.
How pandoc extracts media
Pandoc, the engine behind the converter on this site, handles extraction inside its docx reader. With media extraction enabled, every embedded image is written out under the name it carried in the package: image1.png, image2.jpeg, and so on, collected into a media folder that sits next to the converted document.
The Markdown output references exactly those paths, so the note and its media folder travel as a set. Download the result as a ZIP and you receive both at once: the .md file plus every image it mentions. Unpack the archive anywhere and the links are already correct, because the references are relative to the note.
Two details are worth knowing. Names come from the docx package, not from your captions, so a photo labeled Survey Site B may land as image7.png. And numbering restarts per document: every Word file begins at image1 again, which turns into a collision problem the moment several converted documents share one folder.
Base64 inline or a separate folder
Base64 mode takes the opposite approach: images are embedded directly in the Markdown as data URIs instead of being written to disk. The result is one self-contained file with no media folder to lose, which is convenient when a note has to travel as a single attachment or survive being pasted between tools.
For a vault, real files usually win. Data URIs inflate size by about a third, and a few screenshots can push a note into multi-megabyte base64 text that makes the editor feel slow and renders diffs and version control useless. Real files can also be compressed or renamed once, fixing every note that references them; image data frozen inside a note can never be updated in one place.
Obsidian's attachment conventions
Obsidian lets you choose a layout, and two settings matter here. Under Files and links, Default location for new attachments decides where dropped images go: the vault root, the current folder, or a folder you name. Most vaults converge on one dedicated attachments folder for the whole vault.
Converted Markdown arrives with relative references like media/image1.png, which Obsidian resolves against the note's own location, so placement is simple at first: keep the media folder beside the note. New link format controls what Obsidian writes going forward, and relative paths are the safest choice because notes keep working when the vault moves between machines or sync tools.
A workflow that works the first time
First, drop the docx into the converter on this site and keep the image mode on ZIP. The conversion runs entirely in your browser, so unpublished drafts never leave the machine, and the download contains the .md file plus its media folder, already wired together with relative paths.
Second, unpack the ZIP into the vault folder where the note should live, keeping the .md and the media folder side by side. Open the vault and the images render on the first try, because every reference points at a file that actually exists one level away.
Third, tidy up from inside Obsidian, not the file manager. Select an image, drag it into your attachments folder, and Obsidian moves the file and rewrites the reference in the same action. Moving files outside the app leaves stale links behind, because nothing rescans paths that changed behind its back.
When documents collide
Every Word document numbers its images from one, so ten converted papers contain ten different image1.png files. Copy them all into a shared attachments folder and you have silently overwritten nine of them. This is the most common way a migration looks finished and then loses figures weeks later, long after anyone remembers which file came from where.
Batch conversion sidesteps this by giving each source document its own subdirectory inside the ZIP: one note with its media folder, then the next, with no shared namespace between them. If you do want a single vault-wide attachments folder, merge deliberately: rename each document's images with a meaningful prefix, then find and replace the old paths in the Markdown.
Formats Obsidian cannot render
Not everything in a docx is a PNG or JPEG. Office diagrams, Visio pastes, and some copy operations produce EMF and WMF, Windows vector formats that browsers cannot decode. Since Obsidian is built on browser technology, those images stay invisible no matter how correct the paths are, often leaving a figure-shaped hole in the note.
After unpacking, sort the media folder by file type and pull out anything ending in .emf or .wmf. The cheapest fix is to go back to the source document, right-click the figure, and choose save as picture to export a PNG before converting. Then rename the export to match the reference, or edit the reference to match the file.