How to Add Images in Markdown

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

Adding images in Markdown is straightforward once you understand the syntax and how image paths work. This guide covers local and online images, GitHub README examples, clickable images, resizing, centering, captions, alt text, and the common reasons images fail to load. You can test any 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 a blog post.

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

Because of this, the image path matters just as much as the syntax itself.

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.

You can also add an optional title, which most browsers show as a tooltip on hover:

![Project Logo](logo.png "Project Logo")

The title is different from alt text. Alt text is read by screen readers and shown if the image fails to load, while the title only appears as a hover tooltip and isn't required.

If you want a syntax-focused reference instead of a walkthrough, see the Markdown image syntax guide for the full syntax and platform compatibility notes.

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 keep documentation portable because the images travel with the repository. This is the approach most open-source projects use.

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

Using online images in Markdown#

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

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

The tradeoff is that your document depends on the external image staying available. If the file is deleted or the URL changes, the image stops appearing.

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 stay 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)

Animated GIFs use exactly the same syntax as static images: ![Alt text](demo.gif). Video files are different — standard Markdown image syntax doesn't embed them, so they need a platform-specific method or a link instead.

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

Best practice: Store documentation images in a dedicated folder such as /images or /assets instead of scattering 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.

Resizing images in Markdown#

Standard Markdown syntax has no way to control image size. ![Alt](image.png) always displays the image at its native dimensions.

To resize an image, use inline HTML. Many Markdown renderers, including GitHub, support this, although HTML support can vary by platform:

<img src="./images/homepage.png" alt="Homepage Screenshot" width="400">

You can set width, height, or both. Setting only width preserves the aspect ratio in most browsers, which is usually what you want. On GitHub, this works in README files, issues, and pull requests.

If your Markdown needs to stay pure — some renderers strip HTML — the only reliable option is to resize the source image file itself before uploading it.

Centering an image#

Standard Markdown doesn't include image alignment controls. On platforms that allow inline HTML, this pattern centers an image:

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

This is commonly used for logos and banners in GitHub README files.

Adding a caption below an image#

Some Markdown environments allow the HTML <figure> element, which pairs an image with a caption:

<figure>
  <img src="./images/dashboard.png" alt="Sales dashboard with monthly report" width="500">
  <figcaption>Figure 1: Monthly sales dashboard</figcaption>
</figure>

This only works where the renderer allows those HTML elements. For broader compatibility, add the caption as plain Markdown text directly below the image:

![Sales dashboard with monthly report](./images/dashboard.png)

**Figure 1: Monthly sales dashboard**

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 matters most in technical documentation, where it provides context even when images can't be displayed.

Markdown image best practices#

Adding an image is easy, but a few habits keep your documentation organized and easy to maintain as the project grows:

• 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."
• Consider SVG for simple logos and icons when your target platform supports it.
• Confirm every image still loads after moving files or renaming folders.

Why your Markdown images aren't showing#

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

In most cases the Markdown syntax is correct — the issue is the image's location or the file itself. Here are the usual 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, update the path too.

File name doesn't match#

Some platforms treat uppercase and lowercase letters as different filenames, so homepage.png is not the same as 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 file hasn't been committed and pushed, it won't load for anyone else.

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

Broken image URL#

When using online images, verify that the URL opens directly in your browser. If the hosting site removes or renames the file, Markdown can't display it. For important documentation, local images are the 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 when 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 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")

And the inline-HTML patterns for resizing and centering:

<img src="./images/homepage.png" alt="Homepage Screenshot" width="400">
<p align="center"><img src="./images/logo.png" alt="Project Logo" width="200"></p>

Keeping these 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 often communicates more effectively than several paragraphs of text.

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

Before publishing, check every image with a live Markdown preview to confirm it loads correctly and the layout looks as expected. A few extra minutes here prevents broken documentation later.