Markdown image syntax

How to add an image in Markdown, and the questions that come right after it. Paths, links, size, alignment, alt text and dark mode on GitHub. We ran the GitHub examples through GitHub's Markdown API in October 2026 to check what it keeps and what it removes.

The syntax

An image is a link with an exclamation mark in front:

![A cat asleep on a keyboard](images/cat.png "Optional title")

Part	What it does
!	Makes it an image instead of a link.
[A cat asleep…]	The alt text. Screen readers read it, and browsers show it when the image fails to load.
(images/cat.png …)	The image URL or path.
"Optional title"	Shown as a tooltip on hover. Leave it out unless it adds something.

The alt text may be empty, as in ![](cat.png), but only for a decorative image. See Alt text.

Relative and absolute paths

An absolute URL works anywhere the Markdown is shown:

![Build status](https://example.com/badge.png)

A relative path is resolved from the Markdown file's own folder:

![Architecture](docs/architecture.png)
![Architecture](./docs/architecture.png)
![Logo](../assets/logo.png)

On GitHub, a path that starts with / is relative to the repository root, and GitHub points a relative path at whichever branch the reader is viewing. GitHub's docs recommend relative paths for images that live in the repository, because they keep working in clones.

Spaces break a plain path. Encode them as %20, or wrap the path in angle brackets:

![Screenshot](docs/my%20screenshot.png)
![Screenshot](<docs/my screenshot.png>)

Paths are case-sensitive on GitHub. Docs/Logo.png and docs/logo.png are different files there, even if they are the same file on your Mac or Windows laptop.

Reference-style images

When a URL is long, or one image appears several times, give it a label and define the URL once, anywhere in the file:

![The settings page][settings]

[settings]: https://example.com/screens/settings.png "Settings"

Linked images

To make an image clickable, put the image inside a link's square brackets:

[![Open the demo](docs/demo.png)](https://example.com/demo)

Without this, GitHub wraps every image in a link to the image itself, which opens it full size in a new tab.

Image size

Markdown has no syntax for image size. The CommonMark and GitHub Flavored Markdown specs have nowhere to put a width. Use an HTML <img> tag, which most renderers, GitHub included, accept inside Markdown:

<img src="docs/screenshot.png" alt="The dashboard" width="600">
<img src="docs/screenshot.png" alt="The dashboard" width="50%">

Set width only. The height follows and keeps the image's shape.
A percentage is a share of the column the image sits in, not of the image.
On GitHub, width and height are kept, but style, class and loading are removed. CSS such as style="width: 50%" does nothing there.
GitHub also caps every image at the width of the page, so a large image never overflows.

Some Markdown tools add their own size syntax, such as Pandoc's ![alt](cat.png){width=50%}. GitHub does not support it and prints {width=50%} as text after the image. Use <img> when the file will be read on GitHub.

To make an image smaller in bytes, not just on screen, resize the file itself. A width attribute still downloads the whole image.

Alignment

Markdown has no alignment syntax either, and GitHub removes style. The align attribute still works on GitHub:

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

Float an image to the right of the text that follows it:

<img src="docs/icon.png" alt="App icon" width="120" align="right">

Put two images side by side by giving each less than half the width:

<div align="center">
  <img src="docs/light.png" alt="The editor, light theme" width="45%">
  <img src="docs/dark.png" alt="The editor, dark theme" width="45%">
</div>

Leave a blank line between an HTML block and the Markdown after it, or the Markdown may not be parsed.

Dark mode on GitHub

A logo drawn in black disappears on GitHub's dark theme. GitHub supports the HTML <picture> element, so you can name one image per theme:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.png">
  <img alt="Project logo" src="docs/logo-light.png" width="200">
</picture>

The <source> line is used when the reader's theme is dark. The <img> is the light image and the fallback, so give it the alt text and the width. GitHub announced this in its August 2022 changelog, and GitHub's formatting docs still list <picture> as supported (checked October 2026).

You may also see the older fragment method, from GitHub's November 2021 changelog:

![Logo](docs/logo-dark.png#gh-dark-mode-only)
![Logo](docs/logo-light.png#gh-light-mode-only)

It needs no HTML, but only github.com understands it. Other renderers usually show both images. Prefer <picture> for new files.

Alt text

Alt text is what a screen reader says, and what a reader sees when the image fails to load. Write what the image shows and why it is there, in a sentence or less:

![The checkout page with the card form filled in](docs/checkout.png)

Skip "image of" and "screenshot of". The reader already knows it is an image.
For a diagram, give the point of the diagram, not a list of its boxes.
For a badge or a logo, the name is enough: ![Build status](…).
Leave the alt text empty only when the image adds nothing that the text around it does not say.

Images that update themselves

A screenshot in a README goes stale the day the UI changes. The Markdown is fine; the file behind it is old. Someone has to take the screenshot again and commit it, and usually nobody does.

Screenery fixes this at the URL. Your end-to-end tests take the screenshot, CI pushes it, and each screenshot gets a URL whose image follows your default branch:

![The dashboard](https://cdn.screenery.dev/acme/dashboard/home@latest.png)

The URL reads {org}/{project}/{asset}@{channel}.{ext}. It is ordinary Markdown, so every trick on this page still works: <img width> for size, a link around it, and <picture> for dark mode. If your tests also save a dark screenshot, the same URL serves it with ?theme=dark:

<picture>
  <source media="(prefers-color-scheme: dark)"
          srcset="https://cdn.screenery.dev/acme/dashboard/home@latest.png?theme=dark">
  <img alt="The dashboard" src="https://cdn.screenery.dev/acme/dashboard/home@latest.png" width="800">
</picture>

A screenshot with no dark version serves the normal image for ?theme=dark, never a 404. The URL format is on Screenshot URLs, and the rules for when @latest changes are on How @latest moves. For the whole setup, from Playwright test to README, read README screenshots that update themselves or start with Getting started.

FAQ

How do I add an image in Markdown?

Write an exclamation mark, the alt text in square brackets, then the image URL or path in parentheses: ![A cat asleep on a keyboard](images/cat.png). An optional title goes in quotes after the URL.

How do I change the size of an image in Markdown?

Standard Markdown has no size syntax. Use an HTML img tag with a width attribute instead, for example <img src="images/cat.png" alt="A cat" width="400">. GitHub keeps width and height but removes style attributes.

Why does my image show in VS Code but not on GitHub?

The path is usually wrong for GitHub. Paths are case-sensitive on GitHub, a path relative to the Markdown file must still be valid in the repository, and an image that is not committed and pushed does not exist there.

How do I center an image in a GitHub README?

Wrap it in an HTML element with align="center", for example <p align="center"><img src="logo.png" alt="Logo" width="200"></p>. GitHub removes style attributes, so CSS centering does not work.

How do I show a different image in dark mode on GitHub?

Use a picture element. Put the dark image in a source element with media="(prefers-color-scheme: dark)" and the light image in the img element, which is also the fallback.