← Back to Guides
How-ToEmbedding Images in Markdown
Published on 2026-02-22

Embedding Images in Markdown

A complete guide to embedding local images, remote URLs, SVGs, and HTML-controlled images in Markdown documents for PDF and HTML export.

Images are a first-class element in Markdown and render beautifully in both HTML preview and PDF export. This guide covers every method for adding images, from basic URLs to advanced HTML control.

Basic Image Syntax

markdown
![Alt text](https://example.com/image.png)

The three parts:

  • ! — tells the parser this is an image (not a link)
  • [Alt text] — descriptive text shown if the image fails to load, and read by screen readers
  • (URL) — the image source

Adding a Title (Tooltip)

markdown
![Chart showing Q1 growth](./chart.png "Q1 Revenue Chart")

The text in quotes appears as a tooltip on hover in HTML output.

Remote Images

Link to any publicly accessible image URL:

markdown
![Markdown logo](https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg)

Remote images are fetched at render time. Ensure the URL is stable and publicly accessible — broken URLs result in a missing image placeholder.

Image Sizing with HTML

Standard Markdown doesn’t control image size, but you can drop into HTML for precise control:

html
<!-- Fixed width -->
<img src="./diagram.png" alt="System diagram" width="400" />

<!-- Percentage of page width -->
<img src="./chart.png" alt="Chart" style="max-width: 60%;" />

<!-- Centered image -->
<div style="text-align: center;">
  <img src="./logo.png" alt="Logo" width="200" />
</div>

Image Alignment

Float images left or right with text wrapping:

html
<img src="./photo.jpg" alt="Photo" style="float: right; margin-left: 1em; width: 250px;" />

This paragraph text will flow around the image to its left. Add enough text here
so the wrapping is visible. Float layout works best for figures with a caption.

<div style="clear: both;"></div>

Always add <div style="clear: both;"></div> after a floated image to reset the layout.

SVG Images

SVGs are fully supported and render as crisp vector graphics at any zoom level — ideal for logos and diagrams:

markdown
![Architecture diagram](./architecture.svg)

For inline SVGs with raw HTML, paste the SVG code directly into the document. Inline SVGs can be styled with CSS and are included directly in the PDF render.

Images in Tables

markdown
| Product | Preview |
|---------|---------|
| Widget A | ![Widget A](./widget-a.png) |
| Widget B | ![Widget B](./widget-b.png) |

Keep table images small (under 200px wide) so the table columns don’t overflow the page.

Image Captions

Markdown doesn’t have native caption syntax, but you can use HTML:

html
<figure>
  <img src="./chart.png" alt="Revenue chart" style="max-width: 100%;" />
  <figcaption>Figure 1: Revenue by quarter, 2024–2025</figcaption>
</figure>

Or use an italicised line immediately below the image as a convention:

markdown
![Revenue chart](./chart.png)
*Figure 1: Revenue by quarter, 2024–2025*

Best Practices for PDF Output

Practice Reason
Use images ≥ 800px wide Prevents blurriness in print
Keep images < 1 MB Speeds up PDF generation
Use SVG for icons and logos Infinite resolution
Use PNG for screenshots Lossless quality
Use JPEG for photographs Smaller file size
Always write descriptive alt text Accessibility and fallback

Troubleshooting

Image not showing in PDF: The image URL may be inaccessible at render time. Use a reliable CDN or upload the image to your own hosting.

Image appears blurry: The source image is too small. Replace with a higher-resolution version.

Image overflows the page: Add style="max-width: 100%;" to the <img> tag.

SVG not rendering: Some SVGs rely on external scripts. Use a self-contained SVG or convert to PNG.