How to Insert Images in Markdown

Visual content is crucial for engaging documentation and blog posts. Studies show that readers are 65% more likely to remember information when it’s paired with relevant images. This guide will show you everything you need to know about working with images in Markdown, from basic insertion to advanced formatting techniques.

Markdown itself is a simple and easy-to-use markup language that can be used to format almost any document. If you are new to Markdown consider starting with The Markdown Guide.

Local Images

Let’s assume that the images you need are in the images folder:

 ├─ images/
     └─ picture.jpg
     └─ picture-2.jpg
     └─ picture-three.jpg
 ├─ README.md

👉 Pro Tip: Keep in mind that if the file name contains brackets or any other special characters, then image may not display in the rendered document. If you want to know how to properly name files for web projects, check out these guidelines for filenames in web projects.

So, how to add an image in markdown from a local file? The first way to insert local image to markdown document is to use the following syntax:

![Image description](/images/picture.jpg)

👉 Pro Tip: Always use forward slashes (/) in paths, even on Windows systems, to ensure compatibility across platforms. The text in square brackets (“Image description”) is the so-called alternative text, which is important for the following reasons:

1. For accessibility. Screen-reading programs read that. For example, for those who are visually impaired.
2. This text will be displayed instead of the image if the image file cannot be loaded for any reason.
3. It provides context and a description of the image for search engines, helping them to find it.

The part in parentheses is the path to the file. Notice the very first / in front of images. Without this symbol, your document may display normally on your computer, but once uploaded to a server on the Internet, it may stop displaying. This is one of the main reasons why this happens.

The second way to display a local image in markdown publishing is to use the image tag in the body of your document:

<image src="/images/picture.jpg" alt="Image description">

One of the advantages of this method is that you can use additional image control features this way. The specifics depend on the resource on which you are publishing the document.

Either method will get you the results you want, so the choice is yours.

External Images

How to add an image to Markdown from a link? When you need to insert an image that is hosted somewhere on the internet, just use a link to the image:

![Image description](https://picsum.photos/800/600)

or

<image src="https://picsum.photos/800/600" alt="Image description">

If you hoover your mouse over this image, you will see alternative text popping out.

Effective Alt Text

Crafting alt text effectively enhances accessibility and SEO. Compare these examples:

• Poor Alt Text: ![image](/images/picture.jpg)

• Good Alt Text: ![Bar chart showing monthly sales growth from January to June 2024, with a 25% increase](/images/picture.jpg)

For complex images, use ARIA Labels (HTML Method):

<img 
  src="/images/complex-diagram.jpg" 
  alt="Image description"
  aria-label="Detailed description of the diagram and its significance"
>

Image Sizing and Optimization

HTML Method (Recommended)

For precise control over dimensions:

<img src="/images/picture.jpg" alt="Description" width="500" height="300">

Markdown-Native Sizing

Some Markdown processors (like GitHub) support inline sizing, but check for compatibility:

![](image.jpg =100x200)

Or width only:

![](image.jpg =500x)

Support for this syntax varies by markdown processor, so check your platform’s documentation.

Best Practices for Image Optimization

1. File Format Selection:

• JPG: For photographs
• PNG: For screenshots and images with transparency
• SVG: For logos and icons
• WebP: For modern browsers (with fallback)

2. Recommended Dimensions:

• Blog post images: 1200px-1600px wide
• Thumbnails: 150px-300px wide
• Feature images: 1600px-2000px wide

3. File Size Guidelines:

• Hero images: < 200KB
• In-content images: < 100KB
• Thumbnails: < 30KB

Advanced Formatting

Adding Captions

Image captions are an important part of images in markdown document because they provide additional information to the reader. So, how to add a caption to an image in markdown? To set caption for an image using markdown syntax, just add the text in quotes, separated by a space:

![Image description](/images/picture.jpg "Text under the image")

Or with HTML, you can set the figcaption attribute within figure:

<figure>
  <img src="/images/picture.jpg" width="800" height="600" alt="Image description">
  <figcaption>Text under the image</figcaption>
</figure>

Adding Frames and Borders

Sometimes you need to add a frame around an image. For example, if the image and the page have the same background and the image needs to be visually separated. An image in markdown format has no possibility to add design styles, so this is not possible here.

You can try to add a special attribute to the img tag as in the code below:

<img src="/images/picture.jpg" border="5px solid red" />

But alas, that won’t work either. The frame will not be displayed. So, how to add a frame to an image in markdown? There is a solution and a rather unusual one. Found at StackOverflow. All you have to do is to surround the image tag with another one - kbd:

<kbd>
  <img src="/images/picture.jpg" width="800" height="600" alt="Image description" />
</kbd>

While it’s not a bad trick, it’s poorly visible and rather odd for my taste. There is a better way to add a border around an image in markdown. You can use inline styling (but CSS support is required). This gives you a much wider set of options and more control over the look.

<figure>
  <img
    src="https://picsum.photos/800/600" 
    width="800" height="600" 
    alt="Image description" 
    style="border: 2px solid red; border-radius: 5px; padding: 5px;">
  <figcaption>Text under the image</figcaption>
</figure>

or this will also work:

<img 
  src="/images/picture.jpg" 
  width="800" height="600" 
  alt="Image description" 
  style="border: 2px solid red; border-radius: 5px; padding: 5px;"
>

Creating Image Links

To make images clickable in markdown, you can use standard construction:

[![Alt text](/path/to/thumbnail.jpg)](https://denshub.com)

If you click on this image, it will open Den’s Hub blog in a new window.

Responsive Images

To provide even better mobile experience, you can create several copies of your image with various sizes and use the following:

<img 
  src="/images/picture.jpg"
  srcset="/images/picture-300.jpg 300w,
          /images/picture-600.jpg 600w,
          /images/picture-900.jpg 900w"
  sizes="(max-width: 600px) 300px,
         (max-width: 900px) 600px,
         900px"
  alt="Image description"
>

Troubleshooting Common Issues

1. Images Not Loading

• Check file paths (case sensitivity matters)
• Verify file permissions
• Ensure proper URL encoding for special characters

2. Broken Layouts

• Use relative dimensions (%, vw) instead of fixed pixels
• Consider max-width constraints
• Test on different screen sizes

Best Practices Summary

1. Always include meaningful alt text
2. Optimize images before uploading
3. Test across different devices
4. Use appropriate file formats
5. Maintain consistent naming
6. Consider responsive design
7. Keep image paths organized
8. Use descriptive filenames

Further Resources

• MDN Web Docs: Images in HTML
• Web.dev: Image Optimization Guide
• Markdown for Bloggers
• Mastering Markdown Lists
• How to create a table in Markdown

Remember that while Markdown is designed for simplicity, you can always fall back to HTML when you need more control over image presentation. The key is finding the right balance between maintainability and functionality for your specific use case.

😎