How to Add Images in Markdown: Complete Guide

Adding images to Markdown is straightforward. Here's everything you need to know, from basic syntax to advanced techniques.

Basic Image Syntax

![Alt text](image-url)

Example:

![A cute cat](https://example.com/cat.jpg)

Components:

• ! - Indicates an image (vs a link)
• [Alt text] - Description shown if image doesn't load
• (url) - Path to the image

Image with Title (Tooltip)

Add a title that shows on hover:

![Alt text](image-url "Title text")

Example:

![Mountain landscape](photo.jpg "Photo taken in Colorado")

Local vs Remote Images

Local Images (Relative Path)

![Logo](./images/logo.png)
![Screenshot](../assets/screenshot.jpg)

Remote Images (URL)

![Profile](https://example.com/profile.jpg)

Hosted Images

For reliable image hosting, use Linkyhost Free Image Hosting:

1. Upload your image
2. Get a URL
3. Use in your Markdown

Reference-Style Images

For cleaner documents with multiple images:

![First image][img1]
![Second image][img2]

[img1]: https://example.com/image1.jpg
[img2]: https://example.com/image2.jpg "Optional title"

This keeps your content readable while defining image URLs elsewhere.

Image Sizing

Standard Markdown doesn't support sizing, but there are workarounds:

HTML Method (Most Compatible)

<img src="image.jpg" alt="Description" width="500">

Or with height:

<img src="image.jpg" alt="Description" width="500" height="300">

Platform-Specific Syntax

GitHub/GitLab:

![Image](image.jpg)
<!-- No native sizing - use HTML -->

Obsidian:

![[image.jpg|500]]

Some processors:

![Image](image.jpg){width=500px}

Image Alignment

Center with HTML

<p align="center">
  <img src="image.jpg" alt="Centered image" width="400">
</p>

Left/Right Alignment

<img align="right" src="image.jpg" width="200">

This text wraps around the image on the right.

Images as Links

Make an image clickable:

[![Alt text](image.jpg)](https://destination-url.com)

Example:

[![Visit Linkyhost](logo.png)](https://www.linkyhost.com)

Adding Captions

Standard Markdown doesn't support captions, but you can:

Method 1: Italic Text Below

![Sunset photo](sunset.jpg)
*A beautiful sunset over the ocean*

Method 2: HTML Figure

<figure>
  <img src="sunset.jpg" alt="Sunset">
  <figcaption>A beautiful sunset over the ocean</figcaption>
</figure>

Method 3: Table

| ![Sunset](sunset.jpg) |
|:--:|
| *A beautiful sunset* |

Advanced Image Techniques

Image Galleries

You can create simple image galleries using HTML tables or Markdown tables:

| ![Photo 1](photo1.jpg) | ![Photo 2](photo2.jpg) | ![Photo 3](photo3.jpg) |
|:--:|:--:|:--:|
| *Caption 1* | *Caption 2* | *Caption 3* |

For a grid layout with more control, use HTML:

<div style="display: flex; gap: 10px;">
  <img src="photo1.jpg" alt="Photo 1" width="200">
  <img src="photo2.jpg" alt="Photo 2" width="200">
  <img src="photo3.jpg" alt="Photo 3" width="200">
</div>

Note that inline styles are stripped on some platforms like GitHub. Test your gallery on the target platform, or preview it using the HTML Viewer to see the rendered result before publishing.

Lazy Loading Images

For pages with many images, add lazy loading to improve performance:

<img src="large-photo.jpg" alt="Description" loading="lazy" width="800">

The browser will only load the image when it scrolls into view, which reduces initial page load time.

Dark Mode Responsive Images

You can serve different images depending on the user's color scheme using the HTML <picture> element:

<picture>
  <source srcset="logo-dark.png" media="(prefers-color-scheme: dark)">
  <img src="logo-light.png" alt="Logo">
</picture>

This technique works in HTML-compatible Markdown renderers and is useful for documentation sites that support dark mode.

Responsive Images in Markdown

Making images look good on all screen sizes is essential for modern documentation. Here are several approaches:

Using Max-Width for Fluid Images

Prevent images from overflowing their container:

<img src="wide-image.jpg" alt="Description" style="max-width: 100%; height: auto;">

This ensures the image scales down on smaller screens while never exceeding its natural size.

The srcset Attribute for Multiple Resolutions

Serve different image sizes based on the viewport:

<img
  src="photo-800.jpg"
  srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1200.jpg 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  alt="Responsive photo">

This tells the browser to pick the most appropriate image size, saving bandwidth on mobile devices.

Responsive Images on GitHub

GitHub strips most HTML attributes including style and srcset. For GitHub README files, stick with:

<img src="image.jpg" alt="Description" width="600">

The width attribute is preserved on GitHub and provides basic responsiveness since the browser will scale the image down if the container is narrower than the specified width.

Platform-Specific Features

GitHub

<!-- Supported -->
![image](url)
<img src="url" width="500">

<!-- Drag and drop uploads -->
<!-- Paste from clipboard -->

Obsidian

![[image.png]]           <!-- Internal link -->
![[image.png|500]]       <!-- With width -->
![[image.png|500x300]]   <!-- With dimensions -->

GitLab

![image](url)
![image](url){width=500}  <!-- Sometimes supported -->

Jekyll/Hugo

![image]({{site.baseurl}}/assets/image.jpg)

Image Formats

Format	Best For	Transparency
JPG	Photos	No
PNG	Graphics, screenshots	Yes
GIF	Animations	Yes
SVG	Icons, logos	Yes
WebP	Modern web (smaller)	Yes

Organizing Images

Folder Structure

project/
├── README.md
├── docs/
│   └── guide.md
└── images/
    ├── logo.png
    ├── screenshots/
    │   ├── step1.png
    │   └── step2.png
    └── diagrams/
        └── flowchart.svg

Naming Convention

Good:
screenshot-login-page.png
diagram-user-flow.svg
photo-team-2024.jpg

Bad:
IMG_1234.jpg
Screenshot 2024-01-15.png
untitled.png

Common Issues

Image Not Showing

Check:

1. File path is correct (case-sensitive on some systems)
2. File exists at that location
3. URL is accessible (not behind auth)
4. Image format is supported

Broken Image on GitHub

Common causes:

• Using absolute local paths (C:\Users\...)
• Missing file in repository
• Incorrect relative path

Solution:

<!-- Use relative paths from the markdown file -->
![Image](./images/photo.jpg)

Image Too Large

Solutions:

• Resize before uploading
• Use HTML width attribute
• Compress with tools like TinyPNG

Markdown Image Troubleshooting

Images Render in One Processor but Not Another

Different Markdown processors support different features. An image that displays correctly in Obsidian might break in GitHub or a static site generator. Common reasons include:

• Platform-specific syntax: Obsidian's ![[image.png]] does not work on GitHub
• Attribute extensions: The {width=500px} syntax is not universally supported
• Inline styles stripped: GitHub removes style attributes from HTML tags

Solution: Stick to standard Markdown image syntax (![alt](url)) and use the width HTML attribute when sizing is needed. Preview your Markdown on the target platform, or paste it into the HTML Viewer to inspect the rendered output.

Images Load Slowly

Large images slow down page rendering. To fix this:

1. Compress images before uploading (use TinyPNG, ImageOptim, or Squoosh)
2. Use WebP format when the platform supports it
3. Add loading="lazy" to images below the fold
4. Resize images to the actual display size rather than relying on HTML attributes to scale down a 4000px photo

Alt Text Not Displaying

If your alt text shows as literal brackets and text instead of rendering properly:

• Ensure there is no space between ! and [
• Check for unescaped special characters inside the brackets
• Verify the closing ] and ( have no space between them

Correct:  ![My photo](photo.jpg)
Wrong:    ! [My photo](photo.jpg)
Wrong:    ![My photo] (photo.jpg)

Relative Paths Break After Moving Files

When you reorganize your project, image paths break. Strategies to avoid this:

• Use a dedicated /images directory at the project root
• Use hosted image URLs from Linkyhost Free Image Hosting for images shared across multiple documents
• Use reference-style images so you only need to update the URL in one place

Image Hosting Options

For GitHub Projects

• Store in repository /images folder
• Use GitHub's issue image upload trick
• Upload to Linkyhost

For Documentation

• Linkyhost Free Image Hosting
• Imgur (may have reliability issues)
• Cloudinary (has free tier)

For Static Sites

• Store in /static or /assets folder
• Use site's asset pipeline
• CDN for larger images

Choosing the Right Hosting Approach

Approach	Pros	Cons	Best For
Repository storage	Version controlled, always available	Increases repo size	Small images, screenshots
Linkyhost Free Image Hosting	Hosted URLs, no repo bloat	External dependency	Documentation, READMEs
Imgur	Free, widely used	Links can expire, no control	Casual sharing
CDN (Cloudinary, etc.)	Fast delivery, transforms	Setup required	Production sites
Self-hosted	Full control	Maintenance overhead	Enterprise projects

Accessibility Best Practices

Write Good Alt Text

Bad:
![image](photo.jpg)
![](chart.png)

Good:
![Team members at the 2024 company retreat](team-photo.jpg)
![Bar chart showing 50% growth in Q4](growth-chart.png)

Decorative Images

For purely decorative images, use empty alt:

<img src="decoration.png" alt="">

Quick Reference

Basic image:
![Alt text](url)

With title:
![Alt text](url "Title")

As link:
[![Alt](image.jpg)](https://link.com)

With size (HTML):
<img src="url" alt="text" width="500">

Centered:
<p align="center">
  <img src="url" alt="text">
</p>

Reference style:
![Alt][ref]
[ref]: url "title"

Frequently Asked Questions

Can I use base64 encoded images in Markdown?

Yes, but it makes your Markdown huge and hard to read:

![Image](data:image/png;base64,iVBORw0KGgo...)

Not recommended for most use cases. Base64 images inflate file size by roughly 33% compared to the original binary. Use hosted image URLs instead for better readability and performance.

How do I add images in GitHub comments?

Drag and drop, or paste from clipboard. GitHub uploads automatically and inserts the Markdown image syntax for you. This also works in GitHub Issues and Pull Request descriptions.

Why doesn't my image resize work?

Standard Markdown doesn't support sizing. Use HTML <img> tags instead. On GitHub specifically, only the width and height attributes are preserved; inline style attributes are stripped.

Can I use SVG images in Markdown?

Yes, SVG works in most Markdown processors. Some may require HTML:

<img src="diagram.svg" alt="Diagram">

GitHub renders SVG files directly when referenced with standard image syntax. You can preview SVG files using the SVG Viewer before embedding them.

How do I preview Markdown images before publishing?

Several options are available. Most code editors like VS Code have a built-in Markdown preview (Ctrl+Shift+V). You can also paste your rendered HTML into the HTML Viewer to see exactly how it will look. For GitHub-specific rendering, use the "Preview" tab when editing files on GitHub.

Summary

Basic syntax: ![alt](url)

For sizing: Use HTML <img> tags

Best practices:

• Use descriptive alt text
• Organize images in folders
• Use relative paths for portability
• Host images reliably with Linkyhost