Adding images to your blog posts is easy! Here are the different ways you can include images in your MDX content.

Method 1: Using Standard Markdown Syntax

The simplest way to add an image is using standard Markdown syntax:

![Alt text describing the image](/blog-images/my-image.jpg)

This automatically uses Next.js optimized Image component with:

• Automatic lazy loading
• Responsive image sizing
• Optimized formats (WebP when supported)
• Proper width and height attributes

Example with a Local Image

Place your image in /public/blog-images/ and reference it like this:

![Parquet file structure diagram](/blog-images/parquet-structure.png)

Method 2: Using HTML img Tags

You can also use HTML directly in MDX:

<img 
  src="/blog-images/my-image.jpg" 
  alt="Description" 
  width="800"
  height="600"
/>

Method 3: Using Next.js Image Component Directly

For more control, import and use the Image component:

import Image from 'next/image'

<Image
  src="/blog-images/screenshot.png"
  alt="App screenshot"
  width={1200}
  height={800}
  className="rounded-lg shadow-lg"
  priority={true}  // Load immediately (for above-fold images)
/>

Best Practices

1. Optimize Images Before Uploading

• Use appropriate formats:

  • JPG for photos
  • PNG for screenshots and graphics with transparency
  • SVG for icons and logos
  • WebP for best compression (Next.js auto-converts)

• Compress images:

  • Tools: TinyPNG, ImageOptim, Squoosh
  • Target: < 500KB for most images
  • Use responsive sizes when possible

2. Always Include Alt Text

Good alt text improves accessibility and SEO:

✅ Good: ![Dashboard showing query results with 3 columns and pagination controls](/blog-images/dashboard.png)

❌ Bad: ![Image](/blog-images/dashboard.png)

3. Use Descriptive Filenames

✅ Good: parquet-file-structure-diagram.png
❌ Bad: IMG_1234.png

4. Image Sizing

The default MDX image component uses:

• Width: 800px
• Height: 600px (aspect ratio maintained)

For different sizes, use HTML or the Image component directly.

File Organization

Store your images in organized folders:

public/
  blog-images/
    tutorials/
      getting-started/
        step-1.png
        step-2.png
    diagrams/
      architecture.svg
      data-flow.png
    screenshots/
      app-main-view.png

Then reference them:

![Step 1](/blog-images/tutorials/getting-started/step-1.png)

External Images

To use images from external sources, you need to configure Next.js to allow them.

In next.config.ts, add:

export default {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
      },
    ],
  },
};

Then use them in your posts:

![External image](https://example.com/image.jpg)

Image Captions

To add captions, use a combination of image and emphasis:

![Dashboard screenshot](/blog-images/dashboard.png)
*Figure 1: The main dashboard view showing real-time data*

Or use HTML for more control:

<figure>
  <img src="/blog-images/dashboard.png" alt="Dashboard screenshot" />
  <figcaption className="text-center text-sm text-gray-600 mt-2">
    Figure 1: The main dashboard view showing real-time data
  </figcaption>
</figure>

Common Image Sizes

Here are recommended sizes for different use cases:

Use Case	Recommended Width	Format
Full-width screenshot	1200-1600px	PNG/JPG
Inline diagram	600-800px	PNG/SVG
Icon/small graphic	200-400px	PNG/SVG
Hero/featured image	1920px	JPG
Social media preview	1200x630px	JPG

Troubleshooting

Image Not Showing?

1. Check the path: Paths are relative to /public/

   <!-- Correct -->
   ![Image](/blog-images/photo.jpg)
   
   <!-- Incorrect -->
   ![Image](public/blog-images/photo.jpg)
   

2. Check file extension: Match the actual file extension exactly

   <!-- If file is .png, use .png -->
   ![Image](/blog-images/photo.png)
   

3. Check file exists: Verify the file is in /public/blog-images/

Image Too Large?

If images are slowing down your page:

1. Compress the image
2. Use responsive images
3. Add loading="lazy" for below-fold images

Example: Complete Blog Post with Images

Here's a complete example:

---
title: "Building a Data Pipeline"
description: "Step-by-step guide with screenshots"
date: "2025-11-12"
author: "Engineering Team"
tags: ["tutorial", "data-engineering"]
---

# Building a Data Pipeline

Let's build a simple data pipeline from scratch.

## Step 1: Set Up Your Environment

First, install the required tools:

![Installation command in terminal](/blog-images/tutorials/install.png)

## Step 2: Configure Your Pipeline

Here's the architecture we'll build:

![Pipeline architecture diagram](/blog-images/diagrams/pipeline-arch.svg)

The data flows from left to right:
1. Data sources
2. Processing layer
3. Storage

## Step 3: Test Your Pipeline

Run the pipeline and verify the results:

![Pipeline test results showing success](/blog-images/tutorials/results.png)
*All tests passed successfully!*

That's it! You now have a working data pipeline.

Summary

To add images to your blog posts:

1. Place images in /public/blog-images/
2. Reference them using Markdown: ![Alt text](/blog-images/image.jpg)
3. Include descriptive alt text for accessibility
4. Optimize images before uploading
5. Use appropriate formats (JPG, PNG, SVG)

Your images will automatically be optimized by Next.js for best performance!