Word to Markdown With Images

Clean the Word source

Apply Heading 1, Heading 2, and Heading 3 styles to create a dependable content hierarchy. Do not rely on bold text or larger fonts to identify sections. Use Word's list controls for ordered and unordered lists, and remove empty paragraphs that only create visual spacing. Accept or reject tracked changes before conversion so revision marks do not enter the Markdown. Delete comments, hidden text, document metadata, and content outside the intended publishing scope. Review hyperlinks and replace vague labels such as click here with text that explains the destination. Give images a clear role in the document and place them near the related paragraph. If the document contains a caption, keep it as normal text or use a conversion feature that your tool supports. Simplify merged tables and floating objects when the destination needs predictable reading order.

Understand image extraction

A .docx file stores much of its content in a package that includes media files. A conversion tool may extract those files into an asset directory and create references such as . The generated filename may not describe the image, so rename assets carefully and update every reference if you change them. Check whether the converter preserves the original format. JPEG, PNG, and GIF files may behave differently from SVG, EMF, or pasted clipboard objects. Cropped images can also require review because Word may store the original media while displaying only a crop. Alt text may transfer, disappear, or become the image filename. Inspect the rendered page and revise alt text for the final audience. Do not expose private images from the source document through a public asset folder without checking permissions.

Repair Markdown after conversion

Open the generated Markdown as plain text and inspect the first pass. Confirm that the title uses one top-level heading and that later sections follow a sensible order. Search for broken image paths, empty links, duplicated paragraphs, and leftover Word-specific markup. Check list indentation and table separators because small syntax errors can change the rendered page. Review curly quotes, nonbreaking spaces, and special characters that may need escaping. Word page breaks do not have a consistent Markdown equivalent, so remove them or replace them with a meaningful section break. Headers and footers often belong outside the content body. Render the file in its final documentation or publishing system. Compare the result with the Word source, then keep the extracted asset folder with the Markdown file if the links use relative paths.

Working example

A Word heading followed by an embedded diagram and caption can become Markdown with a relative asset link.

Heading 2: Deployment path
Embedded image: deployment-path.png
Caption: Requests pass through the gateway.

## Deployment path

![Deployment path](media/deployment-path.png)

Requests pass through the gateway.

Keep the media directory beside the Markdown file, or change the link to the final asset location before publishing.