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 permanent 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://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* |

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

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

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"

FAQ

Can I use base64 encoded images?

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

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

Not recommended for most use cases.

How do I add images in GitHub comments?

Drag and drop, or paste from clipboard. GitHub uploads automatically.

Why doesn't my image resize work?

Standard Markdown doesn't support sizing. Use HTML <img> tags instead.

Can I use SVG images?

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

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

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