How To Add Images in Markdown

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 images are presented. This article explores the fundamental Markdown syntax for images.

• The basic Markdown syntax for images is ![Alt text](image_url), where the alt text describes the image and the URL points to a local path or remote source.
• To create a linked image, wrap the image syntax inside a Markdown link: [![Alt text](image_url)](link_url).
• Markdown does not natively support image resizing or alignment. Use the HTML <img> tag with width, height, or style attributes for these cases.
• Alt text is critical for accessibility. Keep it short, specific, and focused on what the image conveys in context — screen readers already announce it as an image.
• Most Markdown processors support raw HTML inline, which allows you to use <img> with inline CSS for dimensions, floating, centering, lazy loading, and other advanced styling.

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

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">

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

[![App Platform](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:

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

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;">
  

• Alignment:

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

• 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>
  

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)
  

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

In this tutorial, you covered the core syntax for embedding images in Markdown, including basic images, linked images, and the use of raw HTML for resizing and advanced styling. You also learned alt text best practices for accessibility and how to apply inline CSS when standard Markdown syntax is not sufficient.

You can now embed images in Markdown documents, control their dimensions and alignment using HTML, and write accessible alt text. These techniques apply across GitHub README files, documentation sites, blogs, and any platform that renders Markdown with HTML support.

To continue building on these skills, explore 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
• How To Build a Website in HTML