Word to Markdown with Images: Extraction, Paths, and Alt Text

Converting the text in a Word document to Markdown is straightforward. Converting the images is a separate job: Word stores media inside the .docx package, while Markdown stores only a text reference to an image file.

The reliable workflow is to convert the document structure, extract the image files, give them stable names, and then connect each image to the Markdown with a relative path and useful alt text. This guide shows how to do that without losing track of assets.

The Short Answer

If you have one document and only a few images:

1. Convert the .docx text with WordToMD.
2. Extract the images from a copy of the Word file.
3. Put the images in an images/ or assets/ folder.
4. Add Markdown references such as ![Login settings screen](images/login-settings.png).
5. Preview the final Markdown in its destination.

If you have many documents or many embedded images, use Pandoc with --extract-media. It can create the media files and references in one command, although you should still rename, optimize, and review the assets.

Why Images Behave Differently from Text

A .docx file is a ZIP package containing XML, relationships, styles, and media. Embedded image bytes usually live under word/media/, while relationship files tell Word where each image appears. The document can also contain cropping instructions, floating positions, captions, decorative shapes, and links that do not have direct Markdown equivalents.

Markdown itself does not embed the image bytes. Standard image syntax contains three pieces of information:

![Alternative text](images/architecture-diagram.png "Optional title")

• Alternative text describes the image when it cannot be seen.
• images/architecture-diagram.png tells the renderer where the file lives.
• The optional title may appear as a tooltip, depending on the renderer.

That separation is useful for version control and publishing, but it means a complete migration must manage both the .md file and its assets.

What WordToMD Does with Embedded Images

WordToMD currently focuses on text structure. It converts headings, paragraphs, lists, links, emphasis, and basic tables in your browser, but it does not export embedded images as a separate assets folder.

This is intentional product behavior, not an upload failure. Your document remains local, and the editable Markdown gives you a clean place to add image references after you extract the files. For an image-heavy document, plan the asset workflow before publishing.

Choose the Right Extraction Method

Workflow A: WordToMD Plus Manual Image Extraction

This method keeps the text conversion quick while giving you control over asset names and placement.

1. Convert and save the Markdown

Open the Word-to-Markdown converter, choose the .docx, review the editable result, and download the .md file. Keep the original Word document unchanged until the migration is complete.

2. Extract images from a copy of the DOCX

Make a copy before changing the extension.

On Windows:

1. Enable File name extensions in File Explorer.
2. Copy handbook.docx to a working folder.
3. Rename the copy to handbook.zip.
4. Extract the ZIP archive.
5. Open the extracted word/media/ folder.

On macOS or Linux, a normal archive utility can open the copied .docx directly, or you can duplicate the file and change its extension to .zip.

The media directory may contain PNG, JPEG, GIF, SVG, EMF, or WMF files. Some publishing systems do not handle Word-specific vector formats, so convert unsupported formats to SVG or PNG before adding them to the Markdown project.

3. Match each file to its position

Names such as image1.png and image2.jpeg are package identifiers, not meaningful asset names. Open the extracted files as thumbnails and compare them with the Word document.

Create a simple mapping while you work:

Do not assume numeric order always matches visual order. Headers, repeated logos, backgrounds, and deleted content can affect the internal numbering.

4. Create a portable folder structure

A simple structure works across GitHub, Obsidian, and most static-site generators:

handbook/
├── handbook.md
└── images/
    ├── system-architecture.png
    ├── login-settings.jpg
    └── conversion-result.png

Then reference the files with relative paths:

![System architecture](images/system-architecture.png)

Relative paths keep the document portable. An absolute path such as C:\Users\Name\Desktop\image1.png only works on one computer and should never appear in published Markdown.

5. Write meaningful alt text

Word image captions and Markdown alt text serve different purposes. A caption is visible supporting text; alt text is a concise replacement for the information conveyed by the image.

Weak:

![Image](images/image1.png)

Better:

![Three-stage publishing flow from Word review to Markdown repository to website deployment](images/publishing-flow.png)

For a screenshot, identify the relevant interface and state. For a chart, summarize the conclusion rather than listing every visual mark. For a decorative image that adds no information, use empty alt text:

![](images/decorative-divider.svg)

Do not repeat the surrounding caption word for word unless it is the clearest equivalent description.

6. Preview in the real destination

Markdown renderers differ. A path that works in a local editor can fail after deployment if:

• the repository uses case-sensitive file names;
• the site rewrites asset URLs;
• the Markdown file moves to another directory;
• spaces or non-ASCII characters are handled differently;
• the platform blocks a file format.

Preview the final page on GitHub, in Obsidian, or through the site’s normal build process. Check every image at desktop and mobile widths.

Workflow B: Extract Images with Pandoc

Pandoc is a better fit when the image mapping would otherwise dominate the migration.

pandoc handbook.docx \
  -t gfm \
  --wrap=none \
  --extract-media=./assets \
  -o handbook.md

Pandoc extracts embedded media and writes references into the generated Markdown. Inspect the resulting directory before publishing: the generated hierarchy and names may be technically correct but difficult to maintain.

After conversion:

1. Remove duplicate or unused assets.
2. Rename files with descriptive, lowercase names.
3. Update every Markdown reference after renaming.
4. Convert unsupported formats.
5. Add or improve alt text.
6. Compress large files.

For repeated conversions, see the batch Word-to-Markdown guide.

Image Paths for Common Destinations

GitHub

Store images in the repository and use paths relative to the Markdown file:

![Build status screen](docs/images/build-status.png)

File-name case matters. Build-Status.png and build-status.png can behave like different files when the repository is rendered on a case-sensitive system. The Word-to-GitHub guide covers the rest of the GFM cleanup.

Obsidian

Standard Markdown image syntax remains the most portable choice:

![Research model](attachments/research-model.png)

Obsidian also supports wiki-style embeds, but those are application-specific. Decide whether portability or Obsidian-native behavior matters more before converting every reference. See the Word-to-Obsidian workflow.

Static-site generators

Sites may resolve assets relative to the current Markdown file, a public/ directory, or an import pipeline. Confirm the project’s convention before moving images. A path such as /images/guide/example.png may work on one site but break when the site is deployed under a subdirectory.

Read the Word-to-static-site guide and test through the production build command.

Optimize Assets Before Publishing

Word documents frequently contain images that are much larger than their displayed size. Publishing those originals can slow page loads without improving visible quality.

Use these practical rules:

• Crop away unused areas before export.
• Prefer JPEG or WebP for photographic content.
• Prefer PNG for interface screenshots that need crisp text.
• Prefer SVG for compatible diagrams and logos.
• Resize images to a sensible maximum display width.
• Remove sensitive metadata when the source requires it.
• Keep the original high-resolution files outside the published asset directory.

Avoid converting every image to one format automatically. Screenshots, diagrams, photos, and transparent illustrations have different requirements.

Common Image Problems and Fixes

The Markdown shows a broken-image icon

Check the path relative to the .md file, including capitalization and extension. Then confirm the asset was committed, uploaded, or copied to the deployment output.

The image works locally but not online

The local path may point outside the project, or the deployed site may use a different base URL. Replace machine-specific paths with repository-relative or site-approved paths.

The extracted image looks different from Word

Word may apply cropping, rotation, transparency, borders, or color adjustments as document instructions rather than changing the underlying image. Recreate the final appearance in an image editor and export a publication-ready asset.

A diagram is missing

SmartArt, charts, grouped shapes, and drawing canvases are not always stored as ordinary raster images. Export the object from Word as SVG or PNG, then reference that exported file manually.

The file name changed but the image disappeared

Renaming an asset does not update Markdown automatically. Search the project for the old name and update every reference, including reference-style image definitions.

Final Image Migration Checklist

• The Markdown file has a matching asset folder.
• Every embedded image that carries information was extracted.
• File names are descriptive, stable, and consistent.
• Paths are relative or follow the destination’s documented convention.
• Alt text communicates the purpose of each meaningful image.
• Decorative images use empty alt text.
• Unsupported Word vector formats were converted.
• Oversized assets were resized or compressed.
• No local drive paths remain in the Markdown.
• All images were checked in the final renderer at mobile and desktop widths.

FAQ

Can WordToMD download the images inside my DOCX?

Not currently. WordToMD converts the document’s text structure and provides editable Markdown, but it does not create a separate image assets folder. Use a copied DOCX archive, Word’s web-page export, or Pandoc to extract media.

Can Markdown store an image inside the .md file?

Standard Markdown stores a reference, not the binary image. Some editors accept base64 data URLs, but they make Markdown files large and less portable. A separate asset file with a relative path is usually easier to maintain.

Should I use an absolute URL or a relative image path?

Use a relative path when the image belongs to the same repository or site. Use an absolute HTTPS URL only when the image is intentionally hosted and maintained elsewhere. Avoid URLs you do not control.

How should I handle Word captions?

Keep the caption as visible text near the image and write separate alt text for the image’s meaning. If your publishing system has a figure or caption component, convert the pair to that platform’s supported syntax.

Conclusion

A successful Word-to-Markdown image migration treats the Markdown and its assets as one package. Use WordToMD for a fast, private text conversion, extract the media separately, create deliberate names and paths, and preview the result where it will actually be published. For large or repeatable migrations, switch to Pandoc and automate the extraction step without skipping the final accessibility and path review.