Markdown Images

Adding images to documents makes content more vivid and easier to understand. Markdown provides simple image insertion syntax that supports local images, network images, and other methods. This chapter will detail various uses of Markdown images.

Basic Image Syntax

Syntax Format

![Alt Text](Image URL)
![Alt Text](Image URL "Optional Title")

Examples

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

![Image with title](https://example.com/image.jpg "This is image title")

Effect:

Image Syntax Explanation

Alt Text (Alternative Text)

Alt text is displayed when images cannot load, important for SEO and accessibility:

❌ ![Image](image.jpg) - Missing description
✅ ![Cute Cat](cat.jpg) - Meaningful description
✅ ![Architecture Diagram](architecture.png) - Describes image content

Image Title

Displayed when mouse hovers over the image:

![Product Screenshot](screenshot.jpg "Click to view larger")

Reference Style Images

Syntax

![Alt Text][Image Reference]

[Image Reference]: Image URL "Optional Title"

Examples

Here are two images:

![Logo][logo]
![Icon][icon]

[logo]: https://github.com/github.png
[icon]: https://example.com/icon.png

Effect:

Here are two images:

Advantages of Reference Images

• Centralized management: Unified definition of image URLs
• Easy maintenance: Only need to modify URL in one place
• Reusable: Same image can be used multiple times
• Clear document: Content not interrupted by URLs

Local Images

Relative Paths

![Local Image](./images/photo.jpg)
![Subdirectory Image](./assets/icons/logo.png)
![Parent Directory Image](../photos/album.jpg)

Absolute Paths

![Absolute Path](/home/user/project/images/pic.jpg)

Network Images

Direct Links

![Network Image](https://example.com/image.jpg)
![GitHub Icon](https://github.com/github.png)

Stable CDN

![CDN Image](https://cdn.example.com/images/photo.jpg)

Image Links

Use Image as Link

[![Image Description](Image URL)](Link URL)

Examples

[![Visit GitHub](https://github.com/github.png)](https://github.com)

[![Click to view large image](./thumbnail.jpg)](./large.jpg)

Effect:

HTML Image Tags

More Flexible Control

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

Styled Images

<img src="image.jpg" alt="Description" style="border-radius: 10px; box-shadow: 0 2px 5px rgba(0,0,0,0.3);">

Responsive Images

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

Image Size Control

Markdown Syntax Limitations

Standard Markdown doesn't directly support size adjustment, use HTML:

<!-- Fixed size -->
<img src="image.jpg" width="500" height="300">

<!-- Width adaptive -->
<img src="image.jpg" width="50%">

<!-- Maximum width -->
<img src="image.jpg" style="max-width: 800px; width: 100%;">

GitHub Flavored Markdown

GitHub supports using | separator:

![Image](image.jpg|300)

Image Alignment

HTML Method

<!-- Left align -->
<img src="image.jpg" align="left">

<!-- Right align -->
<img src="image.jpg" align="right">

<!-- Center -->
<center>
    <img src="image.jpg">
</center>

Use div Container

<div style="text-align: center;">
    <img src="image.jpg" alt="Centered image">
    <p>Image description</p>
</div>

Image Captions

Basic Caption

![Image](image.jpg)

*Image 1: This is a sample image*

Numbered Caption

![Architecture Diagram](architecture.png)

**Figure 1**: System architecture diagram

Side-by-side Image Captions

| Figure 1: Component A | Figure 2: Component B |
|----------------------|----------------------|
| ![Figure A](a.jpg) | ![Figure B](b.jpg) |

Image Optimization Recommendations

1. Choose Appropriate Format

Format	Use Case
JPG	Photos, complex images
PNG	Icons, transparent backgrounds
SVG	Icons, vector graphics
WebP	Modern browsers, optimized compression
GIF	Simple animations

2. Compress Images

Use tools to compress image size:

• TinyPNG
• ImageOptim
• Squoosh

3. Use Appropriate Size

✅ ![Thumbnail](thumb-200x200.jpg)
✅ ![Medium Image](medium-800x600.jpg)
❌ ![Huge Image](huge-4000x3000.jpg)

4. Provide Alt Text

✅ ![Product Screenshot](screenshot.jpg "Product feature display")
❌ ![Image](image.jpg)

Image Storage Best Practices

Directory Structure

project/
├── docs/
│   └── README.md
├── images/
│   ├── screenshots/
│   ├── diagrams/
│   └── icons/
└── assets/
    └── logos/

Naming Conventions

<!-- Recommended -->
![System Architecture Diagram](./images/diagrams/architecture.png)
![User Interface Screenshot](./images/screenshots/ui-2024.png)

<!-- Not Recommended -->
![Image 1](./img1.jpg)
![screenshot](./123.png)

Version Control

• Use Git LFS for large files
• Compress images before committing
• Consider using CDN or image hosting

Image Hosting Solutions

1. Local Storage

![Local Image](./images/photo.jpg)

Pros: Complete control, no external service dependency Cons: Increases repository size, slow loading

2. Image Hosting Services

![Hosting Image](https://img.example.com/photo.jpg)

Common Hosting:

• Imgur
• Cloudinary
• Qiniu Cloud
• Alibaba Cloud OSS
• GitHub Repository

3. CDN Acceleration

![CDN Image](https://cdn.example.com/image.jpg)

Image Placeholders

Use Placeholder Services

![Placeholder](https://via.placeholder.com/300x200?text=Placeholder+Image)

Common Placeholder Services:

• Placehold.co
• Placeholder.com
• Dummyimage.com

Custom Placeholder

![Image to be added](./images/coming-soon.png)

Image Loading Optimization

Lazy Loading

<img src="image.jpg" loading="lazy" alt="Description">

Deferred Loading

Display thumbnail by default, load high definition on click:

[![Thumbnail](thumb.jpg)](large.jpg)

Special Image Types

SVG Images

![SVG Icon](./icons/logo.svg)

GIF Animations

![Animation Demo](./animation.gif)

Data URI Images

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="Embedded image">

Image Support on Different Platforms

GitHub

• Supports local and remote images
• Images hosted in repository
• Auto-generated thumbnails

GitLab

• Supports drag and drop image upload
• Can paste images directly

Typora

• Supports drag and drop image insertion
• Can copy and paste images
• Auto-manages relative paths

VS Code

• Needs preview plugin
• Supports relative path links
• Image hover display

Image Security

Prevent Hotlinking

• Use reference images
• Consider adding watermarks
• Use reliable image hosting

Verify Source

<!-- From trusted sources -->
![Official Documentation](https://docs.python.org/images/logo.png)

<!-- Unknown sources, use with caution -->
![Unknown Image](https://random-site.com/image.jpg)

Practical Examples

Article Illustrations

## Product Introduction

Our product has the following features:

![Product Interface](./images/product-ui.jpg)

As shown above, the interface is simple and easy to use.

Technical Documentation Flowcharts

## Workflow

System execution flow is as follows:

![Flowchart](./images/diagrams/workflow.png)

**Figure 1**: System workflow diagram

Tutorial Step Images

### Step 1: Install Software

![Installation Interface](./images/screenshots/install.png)

As shown above, click "Next" to continue installation.

### Step 2: Configure Settings

![Configuration Interface](./images/screenshots/config.png)

After completing configuration, click "Save".

Image Gallery

## Portfolio Display

| Work 1 | Work 2 | Work 3 |
|--------|--------|--------|
| ![Work1](./gallery/work1.jpg) | ![Work2](./gallery/work2.jpg) | ![Work3](./gallery/work3.jpg) |

*Figure 1*: Selected works display

Common Questions

Q: Image not displaying?

A: Check the following:

• Is URL correct
• Does file exist
• Are permissions correct
• Is network accessible

Q: How to adjust image size in Markdown?

A: Use HTML tags:

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

Q: Images loading slowly?

A:

• Compress image size
• Use CDN
• Use lazy loading
• Provide WebP format

Q: How to batch insert images?

A: Use scripts or editor plugins for automation.

Summary

This chapter detailed Markdown image usage:

• Basic syntax: ![alt](url) format
• Reference images: Centralized image URL management
• Local and network images: Multiple image sources
• Size and alignment: HTML control
• Optimization recommendations: Format selection, compression, naming
• Best practices: Reasonable directory structure and naming

Mastering image usage will make your documents more vivid and professional.

Next: Learn how to create Markdown Tables.