Blog Post Image Processing

Process and optimize images for blog posts with ImageMagick, then add them using the appropriate Astro components.

When to Use

Apply this skill when:

• •Adding hero images to blog posts
• •Adding screenshots or UI images to posts
• •Processing images for blog content
• •Optimizing existing images

Image Component Selection

CRITICAL: Choose the right component for the image type:

ImageLightbox is STRONGLY PREFERRED for screenshots and UI images. Users need to click and examine details closely.

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