How to Add Images in Markdown

Images help explain ideas that are difficult to describe with text alone. Whether you're creating a GitHub README, writing technical documentation, or publishing a tutorial, screenshots, diagrams, logos, and illustrations can make your Markdown documents easier to understand.

Fortunately, adding images in Markdown is simple once you understand the syntax and how image paths work. The same image syntax works across most Markdown editors, GitHub repositories, documentation platforms, and static site generators.

In this guide, you'll learn how to insert images using local files and online URLs, create clickable images, write useful alt text, organize image folders, and avoid common problems like broken image links. You can also test every example in the Markdown Editor with live preview before publishing.

How Markdown images work#

Markdown doesn't store images inside the document. Instead, it creates a reference to an image stored somewhere else.

That image can be:

• A file inside your project folder.
• An image hosted on a website.
• A screenshot stored in your GitHub repository.
• An asset used in documentation or blog posts.

When Markdown is rendered, it loads the image from the specified location and displays it as part of the page.

Because of this, choosing the correct image path is just as important as writing the correct Markdown syntax.

Basic Markdown image syntax#

Markdown uses a simple pattern for inserting images:

![Alt text](image-url)

The syntax has two parts:

• Alt text describes the image for accessibility and appears if the image cannot be loaded.
• Image URL or path tells Markdown where the image is stored.

Example using an online image:

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

Example using a local image:

![Homepage Screenshot](./images/homepage.png)

Both examples use the same syntax. The only difference is where the image is stored.

Quick tip: If the image isn't appearing, the problem is usually the file path or URL—not the Markdown syntax itself.

Using local images in Markdown#

Most GitHub repositories and documentation projects store images inside the project folder.

A common structure looks like this:

project/
│
├── README.md
├── images/
│   ├── logo.png
│   ├── homepage.png
│   └── dashboard.png
└── docs/

If your README.md file is in the project root, you can display an image like this:

![Homepage](./images/homepage.png)

Relative paths make your documentation portable because the images travel with the repository. This is the approach used by most open-source projects on GitHub.

If you move either the Markdown file or the image folder later, remember to update the path accordingly.

Using online images in Markdown#

You don't have to store every image inside your project. Markdown also lets you display images hosted on other websites.

Simply use the full image URL instead of a local file path:

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

Online images are commonly used for:

• Company or project logos
• Public icons
• Documentation assets hosted on a CDN
• Images shared across multiple projects

However, remember that your document depends on the external image remaining available. If the image is deleted or the URL changes, it will no longer appear in your Markdown document.

Local images vs online images#

Both approaches work well, but they serve different purposes.

Local images	Online images
Stored inside your repository	Hosted on another website or server
Continue working when the repository is cloned	Require an internet connection
Easier to version with your project	Easy to reuse across multiple projects
Recommended for screenshots and project assets	Better for shared logos, icons, or publicly hosted images

For GitHub README files and project documentation, local images are usually the better choice because they remain part of the repository.

Adding images to a GitHub README#

Images are one of the easiest ways to make a GitHub README more useful.

Many repositories include:

• Project logos
• Application screenshots
• Architecture diagrams
• Animated GIF demonstrations
• Workflow illustrations

A typical project structure might look like this:

project/
├── README.md
├── assets/
│   ├── logo.png
│   ├── demo.gif
│   └── screenshot.png

The README can reference those files using relative paths:

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

Keeping screenshots inside the repository makes it easier to update documentation whenever the project changes.

Best practice: Store all documentation images in a dedicated folder such as /images or /assets instead of placing image files throughout your repository.

Making images clickable#

Sometimes you want readers to click an image and open another page, download a file, or visit your project website.

Markdown allows this by placing the image inside a normal link:

[![Open Documentation](https://example.com/banner.png)](https://example.com/docs)

This combines two Markdown elements:

• The outer link determines where users go after clicking.
• The inner image displays the picture.

Clickable images are commonly used for:

• Project banners linking to documentation
• Logos linking to the project homepage
• Product screenshots linking to live demos
• Download buttons
• Documentation navigation

This technique works on GitHub, most Markdown editors, and many documentation platforms that support standard Markdown.

Writing better alt text#

Alt text is the description inside the square brackets:

![Dashboard showing monthly sales report](./images/dashboard.png)

Good alt text improves accessibility and helps readers understand the image if it doesn't load.

Instead of writing:

• ❌ ![Screenshot]

Write something descriptive, such as:

• ![User login screen]
• ![Project homepage]
• ![Sales dashboard with monthly report]
• ![Network architecture diagram]

Meaningful alt text is especially important for technical documentation because it provides context even when images can't be displayed.

Markdown image best practices#

Adding an image is easy, but following a few best practices makes your documentation look more professional and easier to maintain.

Here are some recommendations used by many open-source projects and documentation teams:

• Store images in a dedicated folder such as /images or /assets.
• Use descriptive filenames like login-page.png instead of image1.png.
• Compress large screenshots before uploading them to reduce repository size.
• Keep image names consistent throughout the project.
• Write meaningful alt text instead of generic labels like "Screenshot."
• Use SVG files for logos and icons whenever possible.
• Check that every image still loads after moving files or renaming folders.

These small habits help keep your documentation organized as your project grows.

Why your Markdown images aren't showing#

One of the most common problems beginners face is that the image simply doesn't appear.

In most cases, the Markdown syntax is correct—the issue is with the image location or file itself.

Here are the most common causes.

Incorrect file path#

The image path must match the actual folder structure.

For example, if your image is stored inside an images folder, this will work:

![Homepage](./images/homepage.png)

If the folder name or file location changes, you'll need to update the path as well.

File name doesn't match#

Some platforms treat uppercase and lowercase letters as different filenames.

For example, homepage.png is different from Homepage.png.

Always double-check the exact filename before assuming the Markdown syntax is wrong.

Image wasn't added to the repository#

This is especially common on GitHub.

You may reference an image correctly, but if the image hasn't been committed and pushed to the repository, it won't load for anyone else.

Make sure both your Markdown file and image files are uploaded together.

Broken image URL#

When using online images, verify that the URL opens directly in your browser.

If the hosting website removes or renames the image, Markdown won't be able to display it.

For important documentation, local images are often a more reliable choice.

Unsupported or incorrect file extension#

Check that the file extension matches the actual image.

Common formats include:

• .png
• .jpg
• .jpeg
• .gif
• .svg
• .webp

A mismatched extension can prevent the image from loading even if the path is correct.

Quick tip: If your image isn't displaying, check the file path first. Most Markdown image issues are caused by incorrect paths rather than incorrect syntax.

Common Markdown image examples#

Here are some of the image patterns you'll use most often.

![Project Logo](logo.png)
![Homepage](./images/homepage.png)
![Documentation Banner](https://example.com/banner.png)
[![Visit Website](https://example.com/logo.png)](https://example.com)
![Project Logo](logo.png "Project Logo")

Keeping these examples handy makes it easier to remember the syntax while writing documentation, blog posts, or GitHub README files.

Final thoughts#

Images make Markdown documents easier to understand, especially when explaining software, tutorials, or technical workflows. A well-placed screenshot or diagram can often communicate information more effectively than several paragraphs of text.

Whether you're writing a GitHub README, product documentation, or a blog post, using clear image paths, descriptive alt text, and an organized folder structure helps keep your Markdown projects professional and easy to maintain.

Before publishing, preview your document in the Markdown Editor to confirm that every image loads correctly and the layout looks as expected. Spending a few extra minutes checking your images can prevent broken documentation and improve the experience for everyone who reads it.