How to Add an Image to a Markdown Document

Some easy ways to add an image to your post or doc

Visual information is perceived much easier and more effectively than simple text. That’s why they say a picture is worth a thousand words. So you might want to add an image to your document or blog post, too. Below are a few simple ways to add image to markdown publication or document.

Markdown is a simple and easy-to-use markup language that can be used to format almost any document. If you want to learn more about it, read The Markdown Guide.

How to add an image from a file

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

1
2
3
4
5
 ├─ images
     └─ picture.jpg
     └─ picture-2.jpg
     └─ picture-three.jpg
 ├─ README.md

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

The first way to insert local image to markdown document is to use the following code:

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

The part in square brackets 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 / 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.

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

1
<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.

When you need to insert an image into a document that is somewhere on the internet, just use a link to the image:

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

or

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

https://picsum.photos/800/600

How to add a caption to an image

In the markdown code, just add the text in quotes, separated by a space:

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

In HTML code, you must use the attribute caption:

1
2
3
4
<image
  src="/images/picture.jpg"
  alt="Image description"
  caption="Image caption">

https://picsum.photos/800/600
Image caption

How to add a frame to an image

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:

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

But alas, that won’t work either. The frame will not be displayed.

Nevertheless, 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:

1
2
3
<kbd>
  <img src="/images/picture.jpg" />
</kbd>

Cool!