Markdown Syntax:

How to add images in Markdown files

Summary

This guide explains how to embed images in Markdown files, covering paths, alt text, title text, sizing (height and width), and HTML fallback option. Learn best practices for including images in Markdown documentation and Git repositories.

Published:

2025-04-07

Updated:

2025-04-08

Reading time:

02:56

Author:

Jonas Jared Jacek

Tags:

markdown

License:

CC BY-SA 4.0

Permalink:

How to add images in Markdown

Introduction #

Adding images in Markdown is simple. This guide explains how to add images with various attributes, manage image files, and use Hypertext Markup Language (HTML) as a fallback for advanced control.

Basic image syntax in Markdown #

To insert an image in Markdown, use the following syntax:

![Alt text](images/image.jpg)

• ![Alt text] defines the alternative text for the image.
• (path/to/image.jpg) specifies the path to the image file.

The image path can be relative or absolute, depending on where your image is stored in relation to your Markdown file.

Adding alt attribute information #

The alternative text, or alt attribute, improves accessibility and searchability. As you can see in the previous section, the alt attribute is written directly inside the square brackets in the Markdown image syntax:

![A flowchart of the application architecture](./images/architecture.svg)

This text is shown when the image fails to load or is read by screen readers.

Best practices for alt text #

Use an empty alt attribute for decorative images like backgrounds. For informative images, describe the image.

<!-- Empty alt for decorative images -->
![](background-pattern.png)

<!-- Descriptive for informative images -->
![Diagram of network topology](network.png)

Adding title attribute information #

To add a tooltip or additional context, include a title in quotes directly after the image path:

![Architecture diagram](./images/architecture.svg "Click to view full size")

When a user hovers over the image, the title appears as a tooltip.

Not all Markdown processors support the title attribute. See the Markdown parser feature comparison.

Adding height and width information #

Standard Markdown does not support image sizing, but some processors support extended syntax:

![Logo](logo.png){width=200px}

Not all Markdown processors support height and width attributes. See the Markdown parser feature comparison.

Alternatively, to define height and width, use the HTML <img> tag inside your Markdown file. This approach gives you more control over how your image appears in rendered documents:

<img src="chart.svg" alt="Sales chart" width="400" height="300">

Adding images with a CSS class #

Several Markdown renderers support adding CSS classes to images, typically through extended syntax or plugins. Here are the most notable ones:

Markdown-it #

Markdown-it, CommonMark-compatible, supports adding classes via attributes syntax:

![alt](image.png){.my-class}

Requires the markdown-it-attrs plugin.

Pandoc #

Pandoc supports attribute syntax for classes:

![alt](image.png){.class .another-class key=val}

Works natively without plugins.

Kramdown #

Kramdown, used by Jekyll, supports inline attribute lists (IALs):

![alt](image.png){: .my-class}

MultiMarkdown #

MultiMarkdown allows classes via:

![alt][img-id]
[img-id]: image.png "title" {.class}

Not all Markdown processors support class attributes. See the Markdown parser feature comparison.

In most other cases, to style your image using Cascading Style Sheets (CSS), you must also fall back to using HTML.

Fallback: Using HTML for full control #

Markdown is designed to be simple, so it does not support advanced formatting features out of the box. When you need full control, use raw HTML:

<img src="./images/architecture.svg"
     alt="Architecture Diagram"
     title="Click to enlarge"
     width="600"
     height="400"
     class="img-border img-center">

This gives you the ability to define classes, dimensions, alt text, and title attributes all at once.

Images in Git repositories #

If you are working in a Git repository, place the image file within your project structure. Use relative paths to ensure portability:

![Diagram](./assets/diagram.svg)

Git-LFS #

Use Git LFS (Large File Storage) for binary files like images. It replaces the assets with pointers, preventing repository bloat and speeding up Git operations.

Unlike regular Git, which struggles with binary files, LFS stores them externally, reducing bandwidth and storage costs while maintaining seamless version control.

For binary image files (like GIF, PNG, JPG), use Git Large File Storage (Git-LFS) to avoid bloating your repository:

1. Install Git-LFS:

   git lfs install
   

2. Track binary image files:

   git lfs track "*.gif"
   git lfs track "*.png"
   git lfs track "*.jpg"
   ...
   

3. Commit normally. Git-LFS will handle the large files.

SVG files do not need to be added to Git-LFS since they are text-based.

Further readings #

Sources and recommended, further resources on the topic:

• Markdown cheat sheet – Images
• Git Large File Storage (Git LFS)
• MDN Web Docs – HTML element

Author

Jonas Jared Jacek (J15k)

Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/

<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/how-to-add-images-to-markdown-files">How to add images in Markdown files</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>