Images in Markdown - Complete Guide

Images make documentation easier to understand. Markdown image syntax looks like a link with an exclamation mark ! in front.

Basic Image Syntax

![Alt text](image-url)

• The ! tells Markdown this is an image, not a link.
• The text inside [] is the alt text — shown when the image fails to load and read by screen readers.
• The URL inside () is the image source — a relative path or a full URL.

![A beautiful sunset](https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800)

HTML equivalent:

<img src="https://example.com/image.jpg" alt="A beautiful sunset" />

Local Images

For images stored in your project, use a relative path:

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

![Screenshot](../assets/screenshot.png)

Images with a Title

Like links, you can add a title (tooltip on hover) after the URL:

![Markdown logo](./markdown-logo.png "The official Markdown logo")

The title appears when a user hovers over the image in a browser.

Linking an Image

To make an image clickable (link to a URL when clicked), wrap the image syntax inside a link:

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

Example:

[![Meshworld logo](./logo.png)](https://meshworld.in/)

Clicking the image opens https://meshworld.in/.

Reference-Style Images

For documents with many images, reference-style syntax keeps the body text clean. Define the image reference at the bottom of the file.

![Logo][meshworld-logo]

[meshworld-logo]: ./logo.png "Meshworld logo"

The reference name (inside []) is case-insensitive and can be placed anywhere below the image tag.

Alt Text — Why It Matters

Alt text is not optional:

• Accessibility: Screen readers read alt text aloud to visually impaired users.
• SEO: Search engines index alt text to understand image content.
• Fallback: If the image fails to load, the alt text is displayed instead.

Write alt text that describes what the image shows, not what it is called.

Best Practices

• Always include meaningful alt text.
• Use relative paths for local images — makes your project portable.
• Optimise image file sizes before embedding — large images slow down page loads.
• Prefer descriptive filenames (dashboard-screenshot.png over img001.png).

Quick Reference

![Alt text](url)
![Alt text](url "title")
[![Alt text](image-url)](link-url)
![Alt text][ref]

[ref]: url "title"

Hope you find this helpful!

Keep smiling

Related Articles

Deepen your understanding with these curated continuations.

View All Articles

Markdown 5 min read

Horizontal Rules & Line Breaks in Markdown

Master horizontal rules and line breaks in Markdown. Learn how to separate sections with ---, ***, or ___ and when to use trailing spaces vs blank lines.

Hinal Acharya Aug 09, 2021

Markdown 5 min read

Mastering Blockquotes in Markdown - Complete Guide

Learn how to use blockquotes in Markdown for quotes, callouts, and notes. Covers basic syntax, nested blockquotes, multi-paragraph, and best practices.

Hinal Acharya Jun 18, 2021

Markdown 5 min read

Tables in Markdown - Create & Format Data

Learn to create tables in Markdown with pipes and hyphens. Covers column alignment, inline formatting, and best practices for clean data presentation.

Vishnu May 03, 2021