Markdown Image Syntax

The standard Markdown image syntax works in most Markdown editors, GitHub Flavored Markdown (GFM), documentation sites, and note-taking apps.

![Alt text](image.png)

Example

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

The image path points to logo.png, while Project Logo becomes the alternative text shown to screen readers and displayed if the image can't be loaded.

Unlike a standard Markdown link, image syntax starts with an exclamation mark (!).

💡 Pro Tip: Write alt text that describes the image itself, not the filename. Good alt text improves accessibility and makes documentation easier to understand when images fail to load.

Use a public image URL when the image is hosted online.

![Architecture Diagram](https://example.com/images/architecture.png)

Remote images are commonly used for:

• Documentation websites
• Blog posts
• Knowledge bases
• Public documentation portals

Keep in mind that if the image is moved or deleted from the remote server, it will no longer appear in your Markdown document.

If the image is stored inside your project, reference it with a relative path.

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

Example project structure

project/
├── README.md
└── images/
    └── logo.png

Using relative paths keeps your documentation portable and ensures images continue working when the project is cloned or shared.

Markdown supports both relative paths and absolute URLs. The right choice depends on where your document will be used.

In most repositories, relative paths are the safer and more reliable option.

GitHub Flavored Markdown (GFM) fully supports the standard Markdown image syntax.

![Dashboard Screenshot](images/dashboard.png)

For the best experience:

• Store images inside the same repository.
• Keep image filenames simple and descriptive.
• Use relative paths instead of local computer paths.
• Write meaningful alt text for every image.

💡 Pro Tip: GitHub runs on Linux, so filenames are case-sensitive. For example, Logo.png and logo.png are treated as two different files.

Wrap an image inside a Markdown link to make it clickable.

[![Project Logo](images/logo.png)](https://example.com)

This is commonly used for:

• GitHub README badges
• Project logos that link to a website
• Documentation navigation
• Landing pages

The image becomes the clickable element while the destination URL is defined by the outer Markdown link. For more on link syntax, see the Markdown Links guide.

Markdown also lets you add an optional title attribute.

![Project Logo](images/logo.png "MDConvertHub")

Many Markdown renderers display the title as a tooltip when someone hovers over the image. Support varies by platform, so it should be treated as an optional enhancement rather than essential content.

Standard Markdown does not include a syntax for changing image dimensions.

For example, many parsers ignore this syntax:

![Logo](logo.png){width=250}

Some Markdown flavors support custom attributes, but GitHub Flavored Markdown (GFM) and many popular Markdown editors do not. If you need consistent control over image size, use HTML instead.

Most Markdown applications allow inline HTML.

<img src="logo.png" alt="Project Logo" width="250">

You can also specify additional attributes when your platform supports them.

💡 Pro Tip: GitHub supports basic HTML inside Markdown, but some platforms remove or restrict HTML for security reasons. Always preview your document before publishing. See HTML in Markdown for more details.

Most Markdown renderers support common web image formats.

Support depends on the Markdown renderer rather than Markdown itself. If a browser can display the image and the platform allows it, Markdown can usually reference it.

Markdown image support varies slightly across platforms, especially when HTML or custom attributes are involved.

If an image doesn't appear, the problem is usually the file path, filename, or platform—not the Markdown syntax itself. Work through these checks before changing your document.

Why Isn't My Image Showing?#

Check Your Image Path#

Most broken images are caused by an incorrect path.

Suppose your project looks like this:

project/
├── README.md
└── images/
    └── logo.png

The correct Markdown is:

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

A missing folder name or incorrect directory level is enough to prevent the image from rendering.

Watch for Filename Differences#

Many hosting platforms, including GitHub, use case-sensitive file systems.

For example, these filenames are not the same:

Logo.png
logo.png

If your Markdown references logo.png but the repository contains Logo.png, the image won't load.

💡 Pro Tip: Copy the filename directly from your file explorer or repository instead of typing it manually. This helps avoid case and spelling mistakes.

Local Paths vs Public URLs#

A local computer path only works on your own device.

Avoid

C:\Users\John\Pictures\logo.png

Use a relative path instead

![Logo](images/logo.png)

Or use a public image URL if the image is hosted online.

Images with Spaces in Filenames#

Although spaces can work, they often make links harder to read and maintain.

Instead of:

Project Logo Final.png

Prefer:

project-logo.png

Simple, lowercase filenames with hyphens are easier to reference and reduce the chance of mistakes across different tools and operating systems.

Following a few consistent habits will make your Markdown documents easier to maintain and more portable.

• Write descriptive alt text instead of generic labels like "image".
• Keep images inside your project whenever possible.
• Use relative paths for repositories and documentation.
• Compress large images before publishing.
• Choose clear, descriptive filenames.
• Preview your document after moving or renaming files.
• Use HTML only when you need features that standard Markdown doesn't provide.

A quick review can prevent most image-related issues.

• ✓ Every image renders correctly.
• ✓ Alt text describes the image.
• ✓ File paths are correct.
• ✓ Filenames match exactly.
• ✓ Large images are optimized.
• ✓ Remote URLs are publicly accessible.
• ✓ HTML has been tested on the target platform.

Markdown image syntax is intentionally simple, but reliable image rendering depends on using the correct file paths, meaningful alt text, and features supported by your Markdown platform. By following the examples and best practices in this guide, you can add images that work consistently across GitHub repositories, documentation sites, note-taking apps, and other Markdown editors.