Markdown Images

Basic Image Syntax

The Markdown image syntax looks like a link but starts with an exclamation mark. The text inside the square brackets is alt text — it describes the image for screen readers and shows when the image cannot load.

![Mountain landscape](https://example.com/mountain.jpg)

The structure is: ![alt text](URL). The exclamation mark ! is what tells the Markdown processor to embed the image rather than create a text link. Without it, you get a clickable link instead.

![photo](https://example.com/photo.jpg)   <-- image
[photo](https://example.com/photo.jpg)    <-- link

Image with Title

Add a title in double quotes after the URL. The title appears as a tooltip when a user hovers over the image in most browsers and Markdown renderers.

![Sunset over the ocean](https://example.com/sunset.jpg "Taken in Malibu, 2025")

The title is optional. Most people skip it because tooltips are not visible on touch screens and provide limited value for SEO. Use it when a short caption adds useful context that does not belong in the alt text.

Local Images

Instead of a full URL, use a relative path to reference images stored alongside your Markdown file. This is the standard approach for Git repositories, documentation projects, and local notes.

![Project screenshot](./images/screenshot.png)

A typical repository structure for Markdown with images:

my-project/
  README.md
  docs/
    guide.md
    images/
      screenshot.png
      diagram.svg

From guide.md, reference images in the same directory tree:

![Screenshot](./images/screenshot.png)
![Diagram](./images/diagram.svg)

Relative paths work on GitHub, GitLab, VS Code, Obsidian, and MDViewer. The path is resolved from the Markdown file’s location, so ./images/photo.png means “the images folder next to this file.”

Image Size / Resize

Standard Markdown has no syntax for controlling image dimensions. The image renders at its original size. To resize, use an HTML <img> tag instead.

HTML width attribute (most portable)

<img src="logo.png" alt="Company logo" width="300">

Both width and height

<img src="banner.jpg" alt="Event banner" width="600" height="200">

Platform-specific alternatives

Some Markdown processors have their own sizing syntax, but these are not portable:

![alt|300](image.jpg)


![alt|300x200](image.jpg)


<img src="image.jpg" alt="alt" width="300">

The HTML <img> tag with width is the safest choice — it works on GitHub, GitLab, MDViewer, and most processors that allow inline HTML.

Linked Images

To make an image clickable, wrap the image syntax inside a link. The image becomes the link’s content instead of text.

[![App icon](./images/icon.png)](https://example.com)

The structure nests the image inside a link: [![alt](image-url)](link-url). Reading from the inside out: the inner part ![alt](image-url) is the image, and the outer part [...](link-url) wraps it in a link.

Linked image with title

[![Download badge](https://img.shields.io/badge/download-latest-blue)](https://github.com/user/repo/releases "Go to releases page")

This pattern is common for badges in README files. The badge image links to the releases page, downloads section, or CI status.

Image Alignment

Markdown has no built-in alignment syntax. On platforms that support inline HTML, you can center or align images with HTML tags.

Center an image

<p align="center">
  <img src="logo.png" alt="Company logo" width="200">
</p>

Align image to the right

<p align="right">
  <img src="badge.svg" alt="Build status">
</p>

Side-by-side images

<p align="center">
  <img src="before.png" alt="Before" width="45%">
  <img src="after.png" alt="After" width="45%">
</p>

The align attribute on <p> and <div> works on GitHub, GitLab, and MDViewer. Some platforms strip style attributes for security, so align is more reliable than inline CSS.

Reference-Style Images

Like reference-style links, you can separate the image label from the URL. This keeps your Markdown readable when you have many images or long URLs.

![Application screenshot][app-screenshot]
![Architecture diagram][arch-diagram]

[app-screenshot]: ./images/screenshot.png
[arch-diagram]: ./images/architecture.svg "System architecture"

The reference definitions (the lines starting with [id]:) can be placed anywhere in the file, but convention is to put them at the bottom. The identifier is case-insensitive: [App-Screenshot] and [app-screenshot] match the same reference.

Reference-style images are especially useful in documents with many images. They let you read the text flow without long URLs breaking it up, and you can update an image URL in one place without searching through the document.

Base64 / Data URI Images

You can embed an image directly in Markdown using a Base64-encoded data URI instead of a file path or URL. The entire image is stored as text within the Markdown file itself.

![Tiny icon](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...)

To generate a Base64 string from an image file, use the command line:

# macOS / Linux
base64 -i icon.png | pbcopy

# Then paste in your Markdown:
![Icon](data:image/png;base64,PASTE_HERE)

This approach is rarely used because:

• Base64 encoding increases file size by about 33%
• Your Markdown file becomes enormous and hard to edit
• GitHub truncates files over 1 MB, making large embedded images risky
• Version control diffs become unreadable

Use data URIs only for tiny images like icons or single-pixel spacers. For everything else, use a file path or URL.

Platform Support

Not every image feature works on every platform. This table shows which capabilities each major Markdown renderer supports.

Common Mistakes

Forgetting the ! prefix

The most common image mistake. Without the exclamation mark, Markdown renders a text link instead of an embedded image.

![photo](./images/photo.jpg)    <-- correct (image)
[photo](./images/photo.jpg)     <-- wrong (just a link)

Broken relative paths

Relative paths are resolved from the Markdown file’s location, not the project root. If your file is in docs/guide.md and your image is in docs/images/fig1.png, the path should be ./images/fig1.png, not docs/images/fig1.png.

![Figure 1](./images/fig1.png)          <-- correct
![Figure 1](docs/images/fig1.png)       <-- broken (resolves to docs/docs/images/fig1.png)

Oversized images

Embedding a 4000-pixel-wide screenshot without sizing makes your document almost unreadable on smaller screens. Always set a reasonable width with HTML when using large images.

<!-- Too wide on most screens -->
![Screenshot](screenshot-4k.png)

<!-- Better: constrain the width -->
<img src="screenshot-4k.png" alt="Screenshot" width="800">

Spaces in filenames

Spaces in image filenames can break the syntax on some processors. Either rename the file or encode spaces as %20.

![Photo](my photo.png)         <-- may break
![Photo](my%20photo.png)       <-- works everywhere
![Photo](my-photo.png)         <-- best: rename the file

View Markdown Images with MDViewer

MDViewer is a native macOS app that renders Markdown files with full image support. Local and remote images display instantly, relative paths resolve from the file’s parent directory, and HTML <img> tags with sizing and alignment work out of the box. Double-click any .md file in Finder and see it rendered with images, tables, code blocks, and more.

Requires macOS 13.0 or later. Intel and Apple Silicon.

FAQ

How do I add an image in Markdown?

Use the syntax ![alt text](image-url). The exclamation mark at the start tells the Markdown processor to embed the image rather than create a text link. The alt text inside the square brackets describes the image for accessibility. For example: ![Mountain landscape](https://example.com/mountain.jpg) embeds the image inline.

Can I resize images in Markdown?

Standard Markdown has no built-in syntax for image sizing. The most portable workaround is to use an HTML <img> tag: <img src="photo.jpg" width="300">. This works on GitHub, GitLab, MDViewer, and most processors that allow inline HTML. Obsidian has its own non-standard syntax: ![alt|300](image.jpg).

How do I center an image in Markdown?

Wrap the image in an HTML tag with the align attribute: <p align="center"><img src="photo.jpg" width="400"></p>. This works on GitHub, GitLab, and MDViewer. The align attribute is more reliable than style because many platforms strip inline CSS for security.

What image formats does Markdown support?

Markdown itself is format-agnostic — it passes the URL to the browser or renderer. In practice, PNG, JPEG, GIF, WebP, and SVG all work on most platforms. GitHub also supports APNG for animated images. Avoid BMP and TIFF as browser support is inconsistent.

How do I add alt text to a Markdown image?

Alt text goes inside the square brackets: ![Your description here](image.jpg). Write a concise, accurate description of what the image shows. Good alt text improves accessibility for screen reader users and appears as fallback text when the image fails to load. Every image should have meaningful alt text — avoid leaving the brackets empty.

Can I use local images in Markdown?

Yes. Use a relative path instead of a URL: ![Photo](./images/photo.png). The path resolves from the Markdown file’s location. This works on GitHub, GitLab, VS Code, Obsidian, and MDViewer. Keep images in a subfolder like /images or /assets for clean project organization.