How to Add Images in Markdown

Images make Markdown documents more useful and visually clear. Whether you are writing a GitHub README file, documentation, or a blog post, you often need to add screenshots, diagrams, or logos.

In this guide, you will learn how to add images in Markdown using simple syntax, with real examples you can copy and use directly. Practice in the Markdown Editor with live preview on MDConvertHub.

What is image syntax in Markdown?

Markdown uses a simple format to add images:

![Alt text](image-url)

• Alt text — description of the image
• image-url — link or path to the image file

Basic example

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

Image with title

Add optional hover text in quotes:

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

Local image example

For files in your repository:

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

Use a relative path from the Markdown file location. On GitHub, commit the image folder with your README.

Why use alt text?

Alt text matters because it:

• Improves accessibility for screen readers
• Helps search engines understand the image
• Shows descriptive text if the image fails to load

Always write short, accurate alt text — not "image1" or "screenshot" alone.

Where images are used in Markdown

GitHub README

• Project logos
• Screenshots and demos
• Shields.io badges (also image syntax)

Documentation

• UI screenshots
• Architecture or API diagrams

Blogs and guides

• Feature images
• Step-by-step visuals

For README structure and templates, see README.md file example.

Image + link combination

Make a clickable image by wrapping image syntax in a link:

[![Click Here](https://example.com/image.png)](https://example.com)

The outer [...](url) is the link; the inner ![...](image) is the image.

Common mistakes

• Missing ! before the opening bracket — without it you get a text link, not an image
• Wrong path — ./img/photo.png must match the real folder on GitHub
• Broken or very long URLs — test the image URL in a browser first
• Empty or missing alt text — hurts accessibility and clarity
• Huge image files in git — compress screenshots; link to CDN for large assets when possible

Related tools

• Write Markdown with live preview — paste syntax and check image rendering
• Markdown TOC Generator — navigation for long docs with many sections
• Markdown Anchor Link Generator — link to headings near your images
• Markdown cheat sheet — headings, links, lists, and more syntax
• Markdown to HTML — export Markdown with images as HTML for the web

FAQs

How do you add an image in Markdown?

Use ![alt text](image-url). The exclamation mark tells Markdown to render an image instead of a link.

Do images work in GitHub README files?

Yes. You can use full HTTPS URLs or relative paths to images committed in the repository.

What is alt text in Markdown images?

Alt text is the description inside the square brackets: ![This is alt text](url).

Can Markdown images be clickable?

Yes. Wrap the image syntax in a regular link: [![alt](img-url)](https://destination.com).

Final thoughts

Adding images in Markdown is simple but powerful. Once you know the basic syntax, you can use it in GitHub projects, documentation, and blogs to make content clearer and more professional.

Test image syntax in the editor with live preview, then browse more guides on the MDConvertHub blog.