To add an image in Markdown, write . The exclamation mark makes it an image, the square brackets contain a text alternative, and the parentheses contain the image path or URL.
Use a relative path when the Markdown file and image live in the same project. For a GitHub README, commit the image to the repository and link to it with a path such as docs/images/dashboard.png.
Markdown images syntax reference
| Goal | Syntax |
|---|---|
| Inline image |  |
| Image with title |  |
| Reference image | ![alt text][id] with [id]: image.png |
| Linked image | [](https://example.com) |
Markdown images key facts
- The image syntax is an exclamation mark, alt text in square brackets, then the path in parentheses, such as
. - The exclamation mark is the only thing that separates image syntax from link syntax.
- Alt text between the square brackets describes the image for screen readers and shows when the image cannot load.
- Every image compiles to an HTML
<img>element withsrcandaltattributes, plus atitleattribute when a title is given. - Core Markdown has no width or height syntax, so sizing needs a raw HTML
<img>tag or a flavor with attribute support. - A linked image wraps the image in a link, written as
[](https://example.com), so clicking the image follows the link.
Choose the image path for where the document will live
Use a relative path when the image travels with the Markdown file in the same repository or documentation bundle. Use a root-relative path for a known website structure. Use an absolute HTTPS URL only when the external host is stable and hotlinking is permitted.
Write alt text for the image's purpose in context, not as a filename or a list of keywords. Decorative images should use empty alt text in the generated HTML. Standard Markdown does not define image dimensions, captions, or responsive behaviour; these require inline HTML or renderer-specific extensions. See links for clickable images and inline HTML for controlled sizing.
Basic syntax
To insert an image, write an exclamation mark, then the alt text in square brackets, then the image path in parentheses. The path can be a relative path, an absolute path, or a full URL.
Markdown
Rendered output
HTML output
<p><img src="/assets/logo-markdific-v1-transparent-ti.png" alt="A cyan diamond logo on a warm background"></p>
The exclamation mark is what separates image syntax from link syntax. Everything else matches the link format, which makes the two easy to remember together.
Alt text
The text between the square brackets is the image's alt text. It appears when the image cannot load and is read aloud by screen readers, so it should describe what the image shows, not just repeat a keyword.
Markdown
Rendered output
HTML output
<p><img src="/assets/products/markdific-mac-screen-v1-1.png" alt="Markdific app window showing a rendered Markdown document"></p>
Alt text can be left empty with  for purely decorative images, which tells screen readers to skip them. For any image that carries meaning, write a clear description.
Image titles
Add a title by placing a quoted string after the path, separated by a space. The title becomes the image's title attribute, which browsers usually show as a tooltip on hover. It does not replace alt text; the two serve different purposes.
Markdown
Rendered output
HTML output
<p><img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Markdific logo" title="Markdific, the local Markdown editor"></p>
Titles can use double quotes, single quotes, or parentheses. Double quotes are the most common and the most portable.
Reference-style images
Just like links, images support a reference style. You mark the image with a label, then define the path for that label elsewhere in the document. This is handy when the same image appears more than once or when the path is long.
Markdown
Here is the logo: ![Markdific logo][logo]
And again in the footer: ![Markdific logo][logo]
[logo]: /assets/logo-markdific-v1-transparent-ti.png "Markdific"
Rendered output
Here is the logo:
And again in the footer:
HTML output
<p>Here is the logo: <img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Markdific logo" title="Markdific"></p>
<p>And again in the footer: <img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Markdific logo" title="Markdific"></p>
The label is case-insensitive, and the definition line does not render. A reference-style image can carry a title in its definition, just like a reference-style link.
Linked images
To make an image clickable, place the image syntax inside a link. The image sits in the link text position, so clicking the image follows the link.
Markdown
[](https://markdific.com)
Rendered output
HTML output
<p><a href="https://markdific.com"><img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Markdific logo" title="Home"></a></p>
The image's alt text still describes the image, while the outer link controls the click target. For the link half of this pattern, see links.
Image paths: relative, absolute, and remote
An image path can be relative to the current file, absolute from the site root, or a full remote URL. Choose based on where the image lives and how the document is deployed.
Markdown
Rendered output
Relative paths keep a document portable when the images travel with it. Root-relative paths survive page moves within a site. Remote URLs depend on the external host staying available.
Add an image to a GitHub README
Keep the image inside the repository when you want the README to work for forks and offline clones. For example:
project/
├── README.md
└── docs/
└── images/
└── dashboard.png
From README.md, use:
Paths are case-sensitive on GitHub. Dashboard.png and dashboard.png can be different files. Avoid local paths such as /Users/name/Desktop/image.png, because other readers cannot access them.
Choose an image format
| Format | Good for | Main trade-off |
|---|---|---|
| PNG | Screenshots, diagrams, transparency | Larger than WebP for many images |
| JPEG | Photographs | No transparency; repeated saving loses quality |
| WebP | Web photos and illustrations | Older tools may not preview it |
| SVG | Logos, icons, diagrams | Some platforms sanitize or block SVG content |
| GIF | Simple animation | Large files and limited colors |
Markdown does not decide which formats work. The renderer, browser, repository host, or document exporter does.
Image privacy and security
A remote image request can reveal the reader’s IP address and user agent to the image host. Prefer repository-owned or site-owned files for private documents, and do not place credentials or expiring signed URLs in Markdown.
Treat SVG files and raw HTML as active content on platforms that allow scripts or unsafe attributes. Trusted renderers usually sanitize them, but behavior varies. Verify untrusted files before publishing or opening them in a privileged environment.
Flavor differences
Inline images, alt text, titles, reference-style images, and linked images are part of the core image syntax and are broadly supported. Markdown itself has no standard syntax for image width, height, or captions.
| Flavor | Image support | Notes |
|---|---|---|
| CommonMark | Yes | Inline and reference images with alt text and optional title. No standard sizing syntax. |
| GitHub Flavored Markdown (GFM) | Yes | Follows CommonMark. Sizing is done with raw HTML img tags, not Markdown. |
| MultiMarkdown | Yes | Inline and reference images. Supports attribute blocks for width and height. |
| Markdown Extra | Yes | Inline and reference images following original Markdown. |
| Pandoc | Yes | Inline and reference images. Supports attribute syntax for size, and renders a lone captioned image as a figure. |
The core image syntax is identical across flavors. The differences appear only in extras: MultiMarkdown and Pandoc offer attribute syntax for sizing, and Pandoc can promote a standalone image with alt text into a figure with a caption. For sizing in GFM, authors fall back to a raw HTML <img> tag.
Other platforms (Slack, Discord, Reddit, Notion, Obsidian)
Image handling varies widely in chat and note tools:
- Slack: does not render
Markdown image syntax. Images are added as uploads or unfurled from a pasted URL. - Discord: does not render Markdown image syntax. A pasted image URL unfurls into a preview, and files are uploaded directly.
- Reddit: the Markdown image syntax is disabled in most contexts. Images are uploaded through the post editor instead.
- Notion: does not use
. Images are added as blocks by uploading or pasting a URL. - Obsidian: supports standard
and adds its own![[image.png]]wikilink embed syntax, with optional size like![[image.png|200]].
For the full comparison of how flavors differ across all elements, see Markdown flavors.
How Markdific renders it
Markdific renders inline images, so  displays the referenced image in the output. Reference-style images are resolved to their defined path, and a linked image renders as a clickable image. Markdific does not define its own image sizing syntax beyond what the Markdown source provides.
Try it in the Markdific online editor.
Common mistakes and gotchas
- Forgetting the exclamation mark. Without the leading
!, the syntax renders as a link, not an image. - Empty alt text on meaningful images.
gives no description. Empty alt is only for decorative images. - Space between the brackets and parentheses.
![alt] (image.png)breaks the image. The](must be adjacent. - Space in an unescaped path. A space inside the parentheses ends the path early. Wrap the path in angle brackets, like
. - Expecting Markdown to resize images. Core Markdown has no width or height syntax. Use a raw HTML img tag or a flavor that supports attributes.
- Broken relative paths. A relative path is resolved against the file or page location. Moving the file without moving the image breaks it.
- Reversing image and link order. For a clickable image, the image goes inside the link:
[](url).
Best practices
- Write descriptive alt text for every meaningful image, and leave alt empty only for decorative ones.
- Use reference-style images when the same image repeats or the path is long.
- Prefer root-relative or relative paths for images that ship with the document, so links survive moves.
- Add a title only when it gives extra context, since it is not shown to every reader.
- For sizing, use a raw HTML img tag or a flavor with attribute support, and note that it will not be portable.
- Keep image files close to the document when portability matters, so relative paths keep working.
HTML equivalent
Every Markdown image compiles to an HTML <img> element with a src attribute and an alt attribute, plus a title attribute when a title is given. A linked image wraps that img element in an anchor.
Markdown
[](https://markdific.com)
HTML output
<p><img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Markdific logo" title="Markdific"></p>
<p><a href="https://markdific.com"><img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Home"></a></p>
FAQ
How do you add an image in Markdown?
Write an exclamation mark, then the alt text in square brackets, then the image path in parentheses, like . The path can be relative, absolute, or a full URL.
What is alt text in a Markdown image? Alt text is the description between the square brackets. It shows when the image cannot load and is read aloud by screen readers, so it should describe what the image shows.
How do you add a title to a Markdown image?
Place a quoted string after the path, separated by a space, like . The title becomes the img element's title attribute and usually shows as a tooltip.
Can you use reference-style images in Markdown?
Yes. Mark the image with a label and define the path once elsewhere, like ![alt][id] with [id]: image.png. This is useful when the same image repeats or the path is long.
How do you make an image clickable in Markdown?
Put the image syntax inside a link: [](https://example.com). Clicking the image follows the outer link.
How do you resize an image in Markdown? Core Markdown has no sizing syntax. Use a raw HTML img tag with width and height, or a flavor such as MultiMarkdown or Pandoc that supports attribute blocks. These approaches are not portable.
Why is my Markdown image not showing? Common causes are a missing exclamation mark, a broken relative path, a space in an unescaped path, or a space between the brackets and parentheses. Check the path resolves from the file location.
What HTML does a Markdown image produce? It produces an img element with src and alt attributes, plus a title attribute when a title is given. A linked image wraps that img element in an anchor.
How do you center an image in Markdown?
Core Markdown has no alignment syntax. Where inline HTML is allowed, wrap the image in a container such as <p align="center"> or a <div> with a centering style. This is not portable, so some renderers ignore the alignment.
How do you add a caption to a Markdown image?
Core Markdown has no caption syntax. Pandoc turns a standalone image with alt text into a figure and uses the alt text as the caption. Elsewhere, use a raw HTML <figure> with a <figcaption> where inline HTML is allowed.
What image formats can you use in Markdown? Markdown does not restrict formats. The renderer and browser decide what displays, so common web formats like PNG, JPEG, GIF, WebP, and SVG all work when the target can show them.
Do Markdown images work in Slack, Discord, and Notion?
Not with the  syntax. Slack, Discord, and Notion do not render Markdown image markup, so images are added by uploading a file or pasting a URL that the tool unfurls into a preview.
Sources and compatibility references
Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.
Related pages
- Markdown documentation hub
- Links in Markdown
- Escaping characters
- Inline HTML in Markdown
- Code in Markdown
- Markdown flavors compared