🖼️ Working with Images

Insert, resize, and manage images in your markdown documents with both markdown and HTML syntax.

MarkStudio Pro makes it easy to add images to your documents with full support for both markdown syntax and HTML img tags. Images appear at the correct position in your exports, with proper formatting preservation.

📹 Watch: Working with Images

See how to insert, resize, and manage images in your markdown documents.

Basic Image Syntax

Markdown Syntax (Recommended)

The standard markdown syntax for images is simple and clean:

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

Example:

![Company Logo](images/logo.png)
![Screenshot of Dashboard](screenshots/dashboard.png)

💡 Alt Text: The text in square brackets is the "alt text" - a description of the image. This is important for accessibility and appears if the image fails to load.

HTML Syntax (For Advanced Control)

For more control over image size and attributes, use HTML <img> tags:

<img src="path/to/image.png" alt="Description" width="500">

Examples:

<img src="logo.png" alt="Logo" width="200">
<img src="diagram.png" alt="System Architecture" width="600" height="400">
<img src="icon.png" alt="Icon" style="width: 50px;">

Image Paths

Relative Paths

Images in the same folder as your markdown file:

![Image](image.png)

Images in a subfolder:

![Diagram](images/diagram.png)
![Screenshot](assets/screenshots/main.png)

Absolute Paths

You can use full file system paths (Windows or Mac):

![Photo](C:/Users/YourName/Pictures/photo.jpg)
![Chart](file:///C:/Data/charts/sales.png)

⚠️ Path Formats:

Windows: Use forward slashes / or double backslashes \\
Relative paths: Recommended for portability
Spaces in paths: Will work correctly in MarkStudio Pro

Resizing Images

Using HTML Width

<img src="image.png"
     width="400">

Sets width to 400 pixels, height scales proportionally.

Using HTML Height

<img src="image.png"
     height="300">

Sets height to 300 pixels, width scales proportionally.

Using CSS Style

<img src="image.png"
     style="width: 50%;">

Sets width to 50% of container width.

Fixed Dimensions

<img src="image.png"
     width="600"
     height="400">

Sets both width and height (may distort if ratio doesn't match).

💡 Pro Tip: Use only width OR height to maintain the image's aspect ratio. Setting both can distort the image.

Supported Image Formats

Format	Extension	Preview & HTML	PDF Export	Word Export
PNG	`.png`	✅ Yes	✅ Yes	✅ Yes
JPEG	`.jpg`, `.jpeg`	✅ Yes	✅ Yes	✅ Yes
GIF	`.gif`	✅ Yes	✅ Yes	✅ Yes
BMP	`.bmp`	✅ Yes	✅ Yes	✅ Yes
WebP	`.webp`	✅ Yes	✅ Yes	❌ No
SVG	`.svg`	✅ Yes	✅ Yes	❌ No

⚠️ Word Export Limitation: WebP and SVG images are not supported in Word (.docx) export due to limitations in the Word document format. These formats work perfectly in preview, HTML, and PDF exports. For Word export, convert WebP/SVG images to PNG or JPEG.

Images in Exports

PDF Export

Images are embedded at full quality
Resizing (width/height attributes) is respected
Images appear at the exact position in your document
Supports all common formats (PNG, JPEG, GIF, WebP)

Word Export (.docx)

✨ NEW FEATURE: Full image support with correct positioning
Both markdown syntax (![]()) and HTML (<img>) work perfectly
Width and height attributes are preserved
Images maintain quality and aspect ratio
Embedded directly in the .docx file (no external links)
Supported formats: PNG, JPEG, GIF, BMP, TIFF
Not supported: WebP, SVG (use PNG or JPEG instead)

HTML Export

Images are referenced by their original paths
All HTML attributes (width, style, etc.) are preserved
Recommended: Use relative paths for portability

🎉 Export Highlight: MarkStudio Pro correctly handles images in Word export, a feature many markdown editors struggle with. Your images will appear exactly where you placed them!

Advanced Techniques

Center-Aligned Images

<div style="text-align: center;">
    <img src="image.png" alt="Centered Image" width="500">
</div>

Images with Captions

<figure>
    <img src="chart.png" alt="Sales Chart" width="600">
    <figcaption>Figure 1: Q4 Sales Performance</figcaption>
</figure>

Side-by-Side Images

<div style="display: flex; gap: 1rem;">
    <img src="before.png" alt="Before" width="300">
    <img src="after.png" alt="After" width="300">
</div>

Responsive Images (Percentage Width)

<img src="wide-image.png" alt="Banner" style="width: 100%; max-width: 800px;">

Best Practices

Use Descriptive Alt Text: Always provide meaningful alt text for accessibility
Optimize Image Size: Use appropriately sized images (don't embed 4K photos if you only need 500px wide)
Organize with Folders: Keep images in an images/ or assets/ folder
Use Relative Paths: Makes your documents portable across computers
Consistent Naming: Use lowercase, hyphens instead of spaces (e.g., user-dashboard.png)
Test Exports: Preview your document in PDF/Word to verify image positioning
Prefer PNG for Screenshots: Better quality than JPEG for text and UI elements
Prefer JPEG for Photos: Smaller file size with good quality

Troubleshooting

Image Not Showing?

Check the file path is correct (case-sensitive on some systems)
Verify the image file exists at that location
Try using an absolute path to test
Check for typos in the filename or extension

Image Too Large/Small?

Use HTML <img> tag with width attribute
Specify width in pixels (e.g., width="500")
Use only width OR height to maintain aspect ratio

Image Missing in Word Export?

Ensure the image path is accessible when exporting
Try copying images to the same folder as your markdown file
Use relative paths instead of absolute paths
Check image format: Word export only supports PNG, JPEG, GIF, BMP, TIFF
WebP or SVG images? Convert them to PNG or JPEG for Word export

⚠️ Common Mistake: Using backslashes in Windows paths like C:\Users\... won't work in markdown. Change to forward slashes: C:/Users/...

Quick Reference

Basic markdown: ![Alt text](image.png)

HTML with size: <img src="image.png" width="500">

Relative path: images/photo.jpg

Absolute path: C:/Users/Name/Pictures/photo.jpg

Learn About Exporting → ← Back to Docs