How to Add Images in Markdown — Sizing, Alignment, Alt Text & Hosting

Images are how you make Markdown documents actually look like documents. The syntax is dead simple — but the moment you want a 400px wide image, an image aligned to the right, or one with a caption, you start hitting the edge of plain Markdown.

This guide walks through the full toolkit: native syntax, HTML escape hatches, hosting choices, and best practices for alt text and performance.

The basic Markdown image syntax

The standard syntax is one line:

![Alt text](image-url)

Three things make this work:

• ! — the bang prefix that distinguishes images from links
• [Alt text] — text that describes the image for screen readers and SEO
• (image-url) — the source URL (relative or absolute)

A full example:

![A golden retriever sitting in a sunny field](/images/dog.jpg)

You can also add an optional title (shown as a tooltip on hover):

![Alt text](image-url "Optional tooltip title")

Open the Markdown editor and paste any of these snippets to see them render live.

Image as a link

To make an image clickable, wrap the image syntax in a link:

[![Alt text](image-url)](link-url)

Example — clicking the image opens the project's homepage:

[![Markdown Viewer logo](/logo.svg)](https://trymarkdownviewer.com)

This pattern is the foundation of those "badges" you see at the top of every GitHub README.

Resizing images in Markdown

This is where pure Markdown falls short. The basic syntax has no way to set a width or height. You have three options:

Option 1: Use HTML <img> (most flexible)

Markdown allows raw HTML in most renderers. The <img> tag works everywhere:

<img src="/images/dog.jpg" alt="A golden retriever" width="400" />

You can also constrain height, add loading="lazy", and use any other HTML attribute:

<img
  src="/images/dog.jpg"
  alt="A golden retriever"
  width="400"
  height="300"
  loading="lazy"
/>

Option 2: Use a CSS class (docs sites)

Static site generators usually let you add a class via attribute syntax:

![Alt text](image-url){width=400}

The exact syntax depends on the tool — MkDocs, Docusaurus, and Pandoc each have their own dialect.

Option 3: Use a URL with query parameters (image CDNs)

Modern image CDNs accept resize parameters in the URL:

![Alt text](https://example.com/image.jpg?w=400&fit=cover)

Works with Cloudinary, Imgix, Sanity, Vercel Image Optimization, and most modern image hosts. No HTML needed — and you get a smaller download.

Aligning images

There's no native Markdown syntax for alignment, but HTML is well supported:

<p align="center">
  <img src="/logo.svg" alt="Logo" width="200" />
</p>

GitHub explicitly supports align="center", align="left", and align="right". For more sophisticated layouts (side-by-side images, columns), drop into HTML and CSS:

<div style="display:flex; gap:1rem">
  <img src="/images/before.jpg" alt="Before" width="48%" />
  <img src="/images/after.jpg" alt="After" width="48%" />
</div>

Captions

Markdown doesn't have a native caption syntax. Three reliable patterns:

1. Italicized text below the image

![Server architecture](/diagrams/architecture.png)

_Figure 1: Request flow from edge to database._

Renders the caption as italic text immediately below — readable, portable, no HTML.

2. Using <figure> and <figcaption>

<figure>
  <img src="/diagrams/architecture.png" alt="Server architecture" />
  <figcaption>Figure 1: Request flow from edge to database.</figcaption>
</figure>

Semantic, accessible, but slightly more verbose.

3. Title attribute (less common)

![Alt text](image-url "This becomes a tooltip on hover")

Some renderers show the title as a caption — but most use it as a hover tooltip only.

Reference-style images

When you reuse the same image multiple times, or you have several long URLs cluttering your document, switch to reference-style:

Here's the diagram in context: ![architecture]

And again, later: ![architecture]

[architecture]: /diagrams/architecture.png "Server architecture"

You define the URL once at the bottom of the document and reference it by label. This keeps your prose readable when you have lots of images.

Alt text — write it like SEO depends on it (because it does)

Alt text matters for three reasons:

1. Accessibility. Screen readers announce the alt text in place of the image.
2. SEO. Google's image search ranks heavily on alt text, surrounding context, and file name.
3. Fallback. When the image fails to load, the alt text is what your readers see.

Good alt text:

• Describes the image, not the decoration. "Diagram showing request flow" not "An image of a diagram".
• Includes relevant keywords naturally. No keyword stuffing — write what's actually in the picture.
• Is concise. Aim for under 125 characters; assistive tech often truncates at that point.
• Is empty (alt="") for purely decorative images. This tells screen readers to skip them.

<!-- Bad: redundant, no info -->
![Image](/photo.jpg)
![A picture of a chart](/sales.png)

<!-- Good: describes the content -->
![A bearded man typing on a laptop in a sunny café](/photo.jpg)
![Sales by quarter, growing from $1.2M in Q1 to $1.8M in Q4](/sales.png)

<!-- Good: decorative image -->
![](/divider-line.svg)

Image hosting — where to put your image files

You have four practical options:

1. Beside the Markdown file (relative paths)

![A diagram](./images/diagram.png)

Best for READMEs and docs that live next to the source. Path-relative — moves with the document.

2. Public CDN or static folder (/images/...)

![A diagram](/images/diagram.png)

Best for blogs and websites with a fixed /public or /static directory.

3. GitHub asset URLs

When you drag an image into a GitHub issue, comment, or release notes, GitHub generates a URL like:

![A diagram](https://user-images.githubusercontent.com/12345/screenshot.png)

These URLs are permanent and fast — they're a great choice for READMEs and changelogs.

4. Image CDNs (Cloudinary, Imgix, Sanity)

When you need resizing, formats, or large image libraries, use a real image CDN:

![Alt text](https://res.cloudinary.com/demo/image/upload/w_800,f_auto,q_auto/sample.jpg)

Trade-offs: dependency on the CDN, but you get AVIF/WebP delivery, smart cropping, and on-the-fly transformations.

Performance: image optimization for Markdown

Big images are the #1 thing that slows Markdown sites down. Three rules:

1. Compress before you upload. Tools like Squoosh, TinyPNG, and sharp can shrink images 60–90% with no visible loss.
2. Pick the right format. AVIF and WebP beat JPEG and PNG by 30–50%. Most modern CDNs serve them automatically based on the Accept header.
3. Use loading="lazy" on images below the fold:

   <img src="/big.jpg" alt="…" loading="lazy" />
   

For static sites built with Next.js, Astro, or Hugo, the framework's image component handles all of this automatically — usually it's worth replacing raw <img> tags with the framework primitive.

Inline base64 images (small icons only)

You can embed an image directly in the Markdown using a data URL:

![Tiny icon](data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…)

Use this for very small icons (under ~2KB) where the round-trip request would outweigh the bytes. Larger base64 images bloat your Markdown file — keep them in separate files.

SVG images in Markdown

SVG works just like any other image format:

![Logo](/logo.svg)

The advantage: SVGs scale infinitely and stay sharp on retina displays. The catch: some renderers sanitize SVG content (because SVG can contain scripts). If your SVG isn't rendering, check whether the renderer is stripping unsafe tags. Markdown Viewer keeps SVG images intact because we sanitize the SVG markup itself.

Animated GIFs

Use them sparingly — they're huge. A 5-second GIF can be 10MB; the same content as MP4 might be 200KB. For repos that don't allow video, GIFs are still the standard. Otherwise, use HTML <video>:

<video src="/demo.mp4" autoplay loop muted playsinline />

GitHub supports <video> in READMEs as of 2023, and it's a much better experience for everyone.

Image accessibility checklist

Before you publish, run through this list:

• Every meaningful image has descriptive alt text
• Every decorative image has empty alt="" (not omitted entirely)
• No essential information is conveyed by the image alone (color, position, etc.)
• Wide diagrams have a text description or transcript nearby
• Animated images can be paused or auto-pause on prefers-reduced-motion
• All images load with sufficient color contrast against the page

Common Markdown image mistakes

1. Missing alt text. ![](image.png) is technically valid but bad for accessibility and SEO.

2. Spaces in image filenames. ![alt](my image.png) breaks in many renderers. URL-encode it (my%20image.png) or rename the file.

3. Forgetting the bang prefix. [alt](url) is a link, not an image. Easy to miss when copy-pasting.

4. Putting images inside an inline code span. Anything between backticks is escaped, including image syntax.

5. Mixing relative and absolute paths inconsistently. Pick one convention per project and stick to it.

Try it now

Open the Markdown editor and drop an image into the editor — it auto-inserts the syntax for you. You can also use the Insert image toolbar button if you prefer typing the URL.

Related articles

• Markdown cheat sheet — every Markdown primitive on one page
• How to create links in Markdown — internal links, anchors, references
• Markdown table guide — tables, alignment, escaping

Quick reference

![Alt text](url)                                  Basic image
![Alt text](url "Title")                          With tooltip
[![Alt](image.png)](https://site.com)              Clickable image
<img src="x.png" alt="…" width="400" />            Resized (HTML)
<p align="center"><img src="x.png" alt="…" /></p>  Centered

That's the whole toolkit. With these patterns you can handle any image situation Markdown throws at you.