Adding Images to PAELLADOC Blog Posts

[jlcases]

How to Add Images to PAELLADOC Blog Posts

Hello PAELLADOC community! We've updated our blog contribution guidelines with detailed instructions on how to properly add images to your posts.

Image Optimization System

We've implemented a complete Ruby/Jekyll-based image optimization system that automatically:

• Creates responsive versions in multiple sizes (320px to 1920px)
• Converts images to modern formats (WebP, AVIF)
• Generates proper <picture> elements with srcset and sizes
• Ensures accessibility through proper alt text
• NEW: Keeps original images separate and excluded from Git to maintain a lightweight repository

How to Add Images to Your Posts

1. Image Preparation

• Place your original images in the _posts_images_original/ folder at the project root
• Supported formats: .jpg, .jpeg, .png, .gif, .webp
• Recommendation: Use images at least 1200px wide for best quality
• No need to resize or compress beforehand - our system will do it for you
• Important: Original images are excluded from Git (via .gitignore) to keep the repository lightweight

2. Automatic Processing

Your images will be processed automatically in two ways:

• Option 1: When you add files with git add and commit, the pre-commit hook will detect and process them
• Option 2: Run rake optimize_post_images manually to process all images in the folder

The responsive versions will be stored in assets/images/posts_responsive/ organized by image name and size.

3. Referencing in Markdown

In your post, use the Jekyll responsive image tag:

{% responsive_image path: _posts_images_original/image-name.jpg alt: "Accessible description of the image" %}

Additional parameters available:

• class: CSS classes for the picture element
• image_class: CSS classes for the img element
• width: Specific width (optional)
• height: Specific height (optional)
• title: Title to display on hover
• sizes: Custom sizes attribute (responsive by default)

4. Featured Images

For featured images, add in your post's frontmatter:

---
layout: post
title: "Your Post Title"
image: "_posts_images_original/image-name.jpg"
image_alt: "Accessible description of the featured image"
---

Benefits of This Architecture

• Repository Stays Lightweight: Original heavy images are excluded from Git
• Automatic Optimization: Jekyll handles optimization during site build
• Clean Separation: Processed images kept separate from originals
• Modern Formats: Automatic support for WebP and AVIF with fallbacks

Accessibility Recommendations

• Always include descriptive alt text
• Use concise but informative descriptions
• For decorative images, use alt: "" (don't omit the attribute)
• If the image contains text, include that text in the alt attribute

Troubleshooting

• If your images don't appear, verify they're in _posts_images_original/
• If you need to regenerate all images, run rake optimize_post_images
• If you need to reset the configuration, run rake setup_images

Advanced Configuration

The configuration for image processing is in _config.yml under the responsive_image key. If you need to adjust parameters like quality or sizes, consult with the maintenance team.