Markdown Images to Word: Embedding, Sizing & Format Guide

Basic Image Syntax

The standard Markdown image syntax follows this pattern:

![Alt text](path/to/image.png "Optional title")

Each component serves a specific purpose in both web rendering and Word conversion:

• Alt text — Displayed when the image cannot be loaded. In Word, this becomes the image's alternative text property, which is important for accessibility and screen readers. Never leave this empty.
• Path — Can be a relative file path (./images/diagram.png), an absolute path (/home/user/docs/figure1.jpg), or a full URL (https://example.com/photo.png).
• Title — The optional quoted string after the path. Browsers show this as a tooltip on hover. In Word, it is typically ignored by most converters, but Pandoc can map it to a caption.

Relative vs. Absolute Paths

The type of path you use has a direct impact on whether your images survive the conversion process:

# Relative path (recommended for local projects)
![Architecture diagram](./images/architecture.png)

# Absolute path (works on your machine only)
![Architecture diagram](/Users/john/project/images/architecture.png)

# Remote URL (works anywhere with internet)
![Architecture diagram](https://example.com/images/architecture.png)

# Reference-style (keeps Markdown readable)
![Architecture diagram][arch-img]

[arch-img]: ./images/architecture.png "System architecture overview"

Best practice: Use relative paths for local projects and keep all images in a dedicated images/ or assets/ folder at the same level as your Markdown file. This ensures that both Pandoc and online converters can locate the files. If you share your Markdown with collaborators, relative paths maintain portability across different machines.

Since most Markdown parsers support inline HTML, you can use the <img> tag to set explicit dimensions. This works with online converters and Pandoc alike.

# Fixed pixel dimensions
<img src="./images/screenshot.png" alt="App screenshot" width="500" height="300">

# Width only (height auto-calculated to maintain aspect ratio)
<img src="./images/diagram.png" alt="System diagram" width="600">

# Percentage of container width
<img src="./images/photo.jpg" alt="Team photo" width="80%">

# With additional styling
<img src="./images/logo.png" alt="Company logo" width="200"
     style="display:block; margin:0 auto;">

Pandoc extends standard Markdown with attribute syntax that lets you set image dimensions directly in the Markdown image declaration. This is cleaner than inline HTML and is the recommended approach for Pandoc workflows.

# Set width to 50% of the text area
![System architecture](./images/arch.png){width=50%}

# Set exact dimensions in inches
![Dashboard screenshot](./images/dashboard.png){width=5in height=3in}

# Set width in centimeters
![Workflow diagram](./images/workflow.png){width=12cm}

# Set width in pixels (Pandoc converts to inches at 96 DPI)
![Icon set](./images/icons.png){width=400px}

# Combine with other attributes
![Data flow](./images/flow.png){width=80% #fig-flow .diagram}

Pandoc supports the following dimension units: px, cm, mm, in, and %. For Word output, percentages and inches are the most reliable. When you specify only the width, Pandoc preserves the aspect ratio automatically.

Center Alignment

Centering is the most common alignment for figures in academic and business documents. In Markdown, use either HTML or a centered div:

# Method 1: HTML center tag (deprecated but widely supported)
<center>

![Flowchart](./images/flowchart.png)

</center>

# Method 2: Div with style (recommended)
<div style="text-align:center">

![Flowchart](./images/flowchart.png)

</div>

# Method 3: img tag with margin auto
<img src="./images/flowchart.png" alt="Flowchart"
     style="display:block; margin:0 auto; width:70%;">

Pandoc translates centered divs into centered paragraphs in Word. Online converters handle all three methods. After conversion, the image will appear centered between the left and right margins in your Word document.

Left and Right Alignment (Floating)

To float an image to the left or right with text wrapping around it, use HTML with float styling. Note that text wrapping is handled differently in Word versus browsers, so results may vary.

# Float left with text wrap
<img src="./images/headshot.jpg" alt="Author photo"
     style="float:left; margin-right:16px; margin-bottom:8px; width:150px;">

This paragraph text will wrap around the image on the right side.
Continue writing your content normally and the text will flow
naturally around the floated image.

# Float right with text wrap
<img src="./images/sidebar-chart.png" alt="Quick stats"
     style="float:right; margin-left:16px; margin-bottom:8px; width:200px;">

The summary statistics for Q4 are shown in the adjacent chart.
Revenue increased by 23% compared to the previous quarter.

Pandoc Implicit Figures

When a Markdown image is the sole content of a paragraph, Pandoc treats it as a "figure" and uses the alt text as the caption. This is the simplest way to get captions in your Word output.

# This becomes a captioned figure in Word:
![Figure 1: System architecture showing the three-tier design](./images/arch.png)

# This does NOT get a caption (image is inline with text):
The architecture is shown here: ![arch](./images/arch.png) in detail.

The resulting Word document will contain the image followed by an italicized caption paragraph. To enable implicit figures, ensure that the image is the only element in its paragraph—leave blank lines above and below.

# Pandoc command for captioned figures
pandoc input.md -o output.docx

# With a custom reference document for styled captions
pandoc input.md --reference-doc=template.docx -o output.docx

Manual Caption Approach

If you need more control over caption formatting, write captions as separate text elements in your Markdown. This works with any converter:

<div style="text-align:center">

![System architecture](./images/arch.png)

*Figure 1: Three-tier system architecture with load balancing*

</div>

---

<div style="text-align:center">

![Database schema](./images/schema.png)

*Figure 2: Entity-relationship diagram for the user module*

</div>

The italicized text below each image will appear as a caption in the Word document. While this approach requires manual numbering, it gives you full control over caption text and formatting. For long documents, consider using a script to auto-number figures before conversion.

Our Markdown to Word online converter handles images by fetching remote URLs at conversion time and embedding them directly into the Word document. This makes it ideal for documents that reference images hosted on the web (GitHub repositories, CDNs, image hosting services).

Step-by-step:

1. Open markdown-to-word.online in your browser.
2. Paste or type your Markdown with image references. For remote images, use full URLs.
3. Preview the document in the right panel to verify images load correctly.
4. Click "Download DOCX" to generate the Word file with embedded images.
5. Open in Word and fine-tune image sizes and positions as needed.

Pandoc excels at converting Markdown with local images. It reads image files from your file system and embeds them directly into the .docx output. It also supports Pandoc-specific attributes for sizing and captioning.

# Basic conversion (images must be in relative paths)
pandoc report.md -o report.docx

# Specify resource path for images in a different directory
pandoc report.md --resource-path=./assets:./images -o report.docx

# Extract and embed media from remote URLs
pandoc report.md --extract-media=./media -o report.docx

# Use a custom Word template for consistent styling
pandoc report.md --reference-doc=company-template.docx -o report.docx

# Full pipeline with crossref, custom template, and DPI setting
pandoc report.md \
  --filter pandoc-crossref \
  --reference-doc=template.docx \
  --dpi=300 \
  -o report.docx

DPI Considerations for Print

DPI (dots per inch) determines how sharp an image looks when printed. While screen resolution is typically 72–96 DPI, professional printing requires 300 DPI. Here is how to calculate the minimum pixel dimensions for your images:

Pandoc uses 96 DPI by default when converting pixel dimensions to physical sizes. You can override this with the --dpi flag:

# Default: 96 DPI (a 960px image becomes 10 inches wide)
pandoc input.md -o output.docx

# Print-quality: 300 DPI (a 960px image becomes 3.2 inches wide)
pandoc input.md --dpi=300 -o output.docx

Download All Remote Images

If your Markdown references images by URL, this script downloads them locally so Pandoc can embed them. It also updates the Markdown file to use local paths.

#!/bin/bash
# download-images.sh - Download remote images and update Markdown paths
# Usage: ./download-images.sh input.md

INPUT="$1"
IMG_DIR="./images"
mkdir -p "$IMG_DIR"

# Extract image URLs from Markdown
grep -oP '!\[.*?\]\(\K(https?://[^\s)]+)' "$INPUT" | while read -r url; do
    filename=$(basename "$url" | sed 's/[?#].*//')
    echo "Downloading: $url -> $IMG_DIR/$filename"
    curl -sL "$url" -o "$IMG_DIR/$filename"
done

# Replace URLs with local paths in the Markdown
sed -i.bak -E 's|!\[([^\]]*)\]\(https?://[^)]*?/([^/?#)]+)[^)]*\)|![\1](./images/\2)|g' "$INPUT"
echo "Done. Original file backed up as ${INPUT}.bak"

Resize Images for Word

This script uses ImageMagick to resize all images in a directory to a maximum width suitable for A4 Word documents, preserving aspect ratios and converting unsupported formats.

#!/bin/bash
# resize-for-word.sh - Prepare images for Word documents
# Requires: ImageMagick (convert command)
# Usage: ./resize-for-word.sh ./images

IMG_DIR="${1:-.images}"
MAX_WIDTH=1800   # ~6 inches at 300 DPI
QUALITY=90

for img in "$IMG_DIR"/*.{png,jpg,jpeg,gif,webp,svg}; do
    [ -f "$img" ] || continue
    ext="${img##*.}"
    base="${img%.*}"

    # Convert SVG to PNG
    if [ "$ext" = "svg" ]; then
        echo "Converting SVG: $img -> ${base}.png"
        convert "$img" -density 300 "${base}.png"
        img="${base}.png"
    fi

    # Convert WebP to PNG
    if [ "$ext" = "webp" ]; then
        echo "Converting WebP: $img -> ${base}.png"
        convert "$img" "${base}.png"
        img="${base}.png"
    fi

    # Resize if wider than MAX_WIDTH
    width=$(identify -format "%w" "$img" 2>/dev/null)
    if [ "$width" -gt "$MAX_WIDTH" ] 2>/dev/null; then
        echo "Resizing: $img ($width px -> $MAX_WIDTH px)"
        convert "$img" -resize "${MAX_WIDTH}x>" -quality "$QUALITY" "$img"
    fi
done

echo "All images processed for Word compatibility."