Blog Post Images

When to Use Each Component

AutoOptimizedImage - ONLY for hero images:

• Full-width display at top of post
• No user interaction needed
• Sets the visual tone for the article

ImageLightbox - For everything else (PREFERRED):

• Screenshots showing UI, code, or terminal output
• Diagrams that need examination
• Images with text or details users need to read
• Any image where users might want to zoom in

Image Processing Workflow

Step 1: Convert to JPEG

Use ImageMagick to convert PNG to optimized JPEG (85% quality):

magick input.png -quality 85 output.jpg

Why this matters:

• Reduces file size significantly
• 85% quality balances size vs visual quality
• Astro handles further optimization automatically

Step 2: Create Image Directory

For new posts, create the image directory:

mkdir -p src/assets/images/blog/[slug]/

Step 3: Move Image to Directory

Move the processed image:

mv output.jpg src/assets/images/blog/[slug]/filename.jpg

Use descriptive filenames:

• hero.jpg - for hero images
• workflow-screenshot.jpg - descriptive names for other images
• dashboard-before.jpg, dashboard-after.jpg - for comparison shots

Step 4: Add Import Statement

Add to the MDX file's import section:

import ImageLightbox from '../../components/general/ImageLightbox.astro';
import screenshotImage from '../../assets/images/blog/[slug]/filename.jpg';

Import both components if needed:

• AutoOptimizedImage - if adding hero image
• ImageLightbox - if adding screenshots (most common)

Step 5: Add to Post

For hero images (top of post only):

<AutoOptimizedImage src={heroImage} alt="Descriptive alt text for accessibility and SEO" loading="eager" />

For screenshots and UI images (PREFERRED):

<ImageLightbox src={screenshotImage} alt="Descriptive alt text explaining what the screenshot shows" />

Note: ImageLightbox doesn't need loading prop.

Step 6: Format with Prettier

Always format the MDX file after adding images:

npx prettier --write src/content/blog/[slug].mdx

Step 7: Clean Up

Delete original files if still present:

rm input.png  # if original PNG still exists

Alt Text Guidelines

Write descriptive alt text that:

• Explains what the image shows
• Includes relevant keywords naturally
• Helps users understand context
• Supports both accessibility and SEO

Examples:

• ✅ "Cursor interface showing the agent learning git-branch-conventions and git-commit-conventions skills"
• ✅ "Dashboard displaying solar panel energy production and crypto mining metrics"
• ❌ "Screenshot" (too vague)
• ❌ "Image showing the thing" (not descriptive)

Complete Workflow Example

# 1. Convert PNG to JPEG (85% quality)
magick screenshot.png -quality 85 workflow-screenshot.jpg

# 2. Ensure directory exists
mkdir -p src/assets/images/blog/agent-skills-teaching-ai-coding-assistant/

# 3. Move processed image
mv workflow-screenshot.jpg src/assets/images/blog/agent-skills-teaching-ai-coding-assistant/

# 4. Add to MDX file (use StrReplace tool):
#    - Add import: ImageLightbox component and image
#    - Add component usage in appropriate location

# 5. Format with Prettier
npx prettier --write src/content/blog/agent-skills-teaching-ai-coding-assistant.mdx

# 6. Clean up
rm screenshot.png

Important Notes

Astro handles optimization automatically:

• Generates responsive sizes (400px, 600px, 800px, 1024px)
• Converts to modern formats (AVIF, WebP, JPG)
• Creates responsive srcsets

Never manually create multiple image sizes - ImageMagick preprocessing + Astro optimization is the complete pipeline.

Troubleshooting

ImageMagick not found:

• Check installation: magick --version
• Install if needed: brew install imagemagick (macOS)

Image not displaying:

• Verify file exists at expected path
• Check import path matches actual file location
• Ensure slug in path matches post slug
• Run Astro dev server to see build errors

Wrong component used:

• Hero images → AutoOptimizedImage with loading="eager"
• Everything else → ImageLightbox (no loading prop needed)

Quick Reference