How To Add Images in Markdown (Syntax, Examples & Pro Tips)

Introduction

Markdown offers a straightforward, plain-text syntax for formatting documents, including embedding images, for content creation. Its simplicity allows authors to focus on content rather than complex HTML tags. However, Markdown’s strength in simplicity can also be a limitation when you need more control on how your image are presented. This article explores the fundamental Markdown syntax for images.

Prerequisites

• A general knowledge of HTML5. For a comprehensive review of the HTML5 markup language, explore our series, How To Build a Website in HTML.

Adding Images in Markdown

Here’s the syntax for adding images in Markdown. The title is optional:

![Alt text](https://assets.digitalocean.com/articles/alligator/boo.svg "a title")

This results in the following HTML:

<img title="a title" alt="Alt text" src="/images/boo.svg">

Linked Images

With the markdown syntax for links, here’s how you would have a linked image:

[![App Platorm](https://doimages.nyc3.cdn.digitaloceanspaces.com/002Blog/0-BLOG-BANNERS/app_platform.png)](https://www.digitalocean.com/products/app-platform)

This is how the above Linked image looks:

Resizing Images in Markdown

Markdown by itself does not support directly resizing the images. However, we can workaround this problem using the HTML <img> tag. Let’s resize the above image:

<img src="https://doimages.nyc3.cdn.digitaloceanspaces.com/002Blog/0-BLOG-BANNERS/app_platform.png" width="400">

This will resize the image to the mentioned width, in this case, to 400.

This method is supported by most platforms that offers Markdown with HTML support, including GitHub and Jupyter Notebook.

Alt Text Best Practices for Accessibility

Alt text, short for alternative text, is a short description that explains what an image shows. It’s mainly used by screen readers to help people who are visually impaired understand the content of images. It also comes in handy when images don’t load properly. So it is critical that alt texts are clear, specific, and focused on what’s important about the image in its context.

Here are some of the best practices:

• Keep it short. Most of the time, 1 sentence is enough.
• Describe the key elements instead of every detail. Think about what someone would need to understand the image if they couldn’t see it.
• No need to say ‘image of’ or ‘picture of’ as screen readers already do that. But mention if it’s a logo, illustration, or painting.
• Avoid using the same text that’s adjacent to the image.

To know more about accessibility, you can refer to Web Accessibility For Beginners.

HTML Fallbacks and Inline Styling

While Markdown provides a simple and efficient syntax for embedding images, it has inherent limitations when it comes to advanced styling or providing fallback options for different scenarios. For these cases, you can leverage raw HTML directly within your Markdown document. Most Markdown processors support embedding raw HTML, making it a powerful “fallback” when Markdown’s syntax isn’t sufficient.

Opt for HTML <img> tags over Markdown syntax for images when you need to:

• Specify exact dimensions: Markdown doesn’t natively support width or height attributes.
• Apply complex styling: Beyond basic alt text and title (tooltip), Markdown offers no direct way to add CSS styles like borders, padding, or alignment.
• Implement responsive images: Using <picture> or srcset for different image sources based on screen size or resolution.
• Add image captions: While some Markdown flavors might have extensions, standard Markdown doesn’t have a dedicated caption syntax.
• Add custom attributes: Any HTML attribute not supported by Markdown (e.g., loading="lazy", class, id).

Using HTML in Markdown also allows you to use inline CSS for styling images. You can use the style attribute to apply CSS properties directly to an HTML element. For example:

<img src="image_url" alt="Description of image" style="property: value; property2: value2;">

There are a few other inline styles that you can use for images:

• Sizing:

  <img src="image.jpg" alt="A beautiful landscape" style="width: 300px; height: 200px;">
  

  Copy

• Alignment:

  <img src="image.jpg" alt="A floating image" style="float: right; margin-left: 15px;">
  

  Copy

• Centering (requires a wrapper element): To center an image, you need to wrap it in a block-level HTML element like a <div> and apply text alignment or margin auto:

  <div style="text-align: center;">
    <img src="image.jpg" alt="Centered image" style="display: block; margin: 0 auto;">
  </div>
  

  Copy

FAQs

1. What is the correct syntax to insert an image in Markdown?

The basic syntax to insert an image is:

![Alt text](image_url)

The image_url can be a path/URL to the image.

2. How do I add a local image in Markdown?

To add a local image in Markdown, replace image_url in the basic syntax with the local path to the image. For example:

![Alt text](/Users/username/Pictures/example.png)

You can also use relative path:

![Alt text](example.png)

Here, the image is in the same folder as your Markdown file.

3. Can I resize or center images in Markdown?

To resize an image, use the HTML <img> tag:

<img src="image_url" width="400" height="400">

To center an image, we can use the align attribute:

<p align="center">
  <img src="https://doimages.nyc3.cdn.digitaloceanspaces.com/002Blog/0-BLOG-BANNERS/app_platform.png" alt="Alt text" width="600"/>
</p>

4. How do I use images in a GitHub README?

To use images in GitHub, you can:

• Create a folder in the GitHub repository, upload all the images to that folder, and use the relative path in the basic syntax.

  document.md

  ![Alt text](./images/screenshot.png)
  

  Copy

• Alternatively, you can upload the images to your preferred storage bucket, and add the URL to the image.

Conclusion

Markdown’s elegant syntax provides a straightforward and efficient way to embed images in your documents, offering a balance of simplicity and functionality. While it handles most image needs, Markdown alone isn’t enough. The ability to incorporate raw HTML directly, and thereby using inline CSS, within your Markdown allows for greater control when advanced styling, specific dimensions, or responsive image techniques are required.

For a more comprehensive review of the HTML5 markup language, explore our series, How To Build a Website in HTML. You can explore more Markdown-related topics with the following tutorials:

• How To Use Python-Markdown to Convert Markdown Text to HTML
• How To Generate Pages from Markdown in Gatsby
• How To Use Python-Markdown with Flask and SQLite