Skip to main content

Image Optimization Guide

This guide explains how to use the optimized image components and tools in this Docusaurus site to improve loading performance while maintaining the ability to view full-size images.

Overview​

The site includes image optimization features that:

  • Reduce bandwidth usage by serving appropriately sized images
  • Improve loading speed with responsive images and modern WebP format
  • Maintain accessibility with proper alt text and fallbacks
  • Enable full-size viewing through modal components

Components​

OptimizedImage​

Use OptimizedImage for basic responsive images with automatic size optimization:

import { OptimizedImage } from '@site/src/components/OptimizedImage';

<OptimizedImage
  src="docs/resources/courses/science/chemistry-science-unit-study.jpg"
  alt="Chemistry Science Unit Study textbook cover"
  width={400}
  height={300}
/>

Props:

  • src (required): Path to the original image
  • alt (required): Alternative text for accessibility
  • width, height: Optional dimensions
  • loading: 'lazy' (default) or 'eager'
  • sizes: Custom responsive sizes string
  • className: CSS classes

ImageWithModal​

Use ImageWithModal for images that users might want to view in full size:

import { ImageWithModal } from '@site/src/components/ImageWithModal';

<ImageWithModal
  src="docs/resources/courses/math/math-7-good-and-beautiful.jpg"
  alt="Math 7 Good and Beautiful textbook"
  width={300}
/>

This component:

  • Shows a clickable thumbnail with zoom indicator
  • Opens full-size image in modal when clicked
  • Supports keyboard navigation (Enter to open, Escape to close)
  • Prevents body scrolling when modal is open

Image Optimization Script​

Running the Script​

Optimize new images by running:

yarn site:optimize-images [input-dir] [output-dir]

Example:

yarn site:optimize-images docs static/img/optimized

What the Script Does​

The optimization script:

  1. Creates multiple sizes: thumbnail (400px), medium (800px), large (1200px), and original
  2. Converts to WebP: Modern format with better compression
  3. Maintains JPEG fallback: For browser compatibility
  4. Preserves directory structure: Mirrors your docs organization

Generated Files​

For an image like chemistry-science-unit-study.jpg, the script creates:

static/img/optimized/resources/courses/science/
├── chemistry-science-unit-study-thumb.webp (20KB)
├── chemistry-science-unit-study-medium.webp (71KB)
├── chemistry-science-unit-study-large.webp (185KB)
├── chemistry-science-unit-study.webp (779KB)
└── chemistry-science-unit-study.jpg (1.6MB)

Migration Guide​

Before (Regular Images)​

![Chemistry Unit Study](./science/chemistry-science-unit-study.jpg)

After (Optimized Components)​

import { ImageWithModal } from '@site/src/components/ImageWithModal';

<ImageWithModal
  src="docs/resources/courses/science/chemistry-science-unit-study.jpg"
  alt="Chemistry Science Unit Study textbook cover"
  width={400}
/>

Performance Benefits​

Size Reductions​

Original images were 2.5MB-7.5MB each. After optimization:

  • Thumbnail (400px): ~20-40KB (99% reduction)
  • Medium (800px): ~70-200KB (95% reduction)
  • Large (1200px): ~200-600KB (90% reduction)

Responsive Loading​

  • Mobile devices load ~20KB thumbnails instead of 5MB originals
  • Tablets load ~100KB medium images
  • Desktops load appropriate sizes based on viewport

Modern Formats​

  • WebP images are 25-35% smaller than JPEG
  • Automatic fallback to JPEG for older browsers

Best Practices​

  1. Always include alt text for accessibility
  2. Use ImageWithModal for detailed images users might want to examine
  3. Use OptimizedImage for decorative or smaller images
  4. Run optimization script after adding new images
  5. Test on slow connections to verify performance improvements

Technical Details​

Component Architecture​

Both components follow the site's patterns:

  • Function Module Pattern with named parameters
  • 100% test coverage
  • TypeScript interfaces for type safety
  • Responsive design principles

Browser Support​

  • WebP: All modern browsers (Chrome, Firefox, Safari, Edge)
  • Fallback: JPEG for older browsers
  • Responsive images: Picture element with source selection

Accessibility Features​

  • Proper ARIA labels and roles
  • Keyboard navigation support
  • Screen reader friendly markup
  • Focus management in modals