• Image Embedding Support

    Overview

    Successfully implemented comprehensive image embedding support for Chalk that allows authors to embed images using the !!! image.png !!! syntax with automatic optimization and responsive image generation.

    Features Implemented

    1. Parser Support (src/parser/blocks.js)

    • Multiple Formats: Supports png, jpg, jpeg, gif, svg, webp, avif, tiff
    • Metadata Support: YAML frontmatter for image metadata (photographer, license, etc.)
    • Smart Detection: Automatically sets mediatype: "image" for image files
    • Description & Caption: Parses [description] and caption text

    2. Renderer Support (src/renderer/)

    • Responsive Images: Generates <picture> elements with multiple sources
    • Dev Mode: Simple <img> tags for fast development
    • Production Mode: Optimized images with WebP + JPG fallbacks
    • Proper Semantics: Wrapped in <figure> with <figcaption>
    • Accessibility: Proper alt attributes and lazy loading

    3. Image Optimization (src/renderer/index.js)

    • Multiple Sizes: 480w, 768w, 1024w, 1440w responsive breakpoints
    • Format Conversion: WebP (primary) + JPG (fallback)
    • Quality Settings: WebP 85%, JPG 80% for optimal size/quality balance
    • No Upscaling: Respects original image dimensions
    • Error Handling: Graceful fallback for missing/corrupt images

    4. Build Integration

    • Dev Mode Detection: Uses CHALK_DEV_MODE environment variable
    • CLI Integration: Automatically detects watch mode vs build mode
    • Output Management: Images go to /images/ directory
    • Asset Pipeline: Integrates with existing Svelte island bundling

    Usage Examples

    Basic Image

    !!!
photo.jpg
[Alt text for accessibility]
This is the caption that appears below the image.
!!!

    Image with Metadata

    !!!
photographer: Jane Doe
license: CC BY 4.0
date: 2024-01-01
---
landscape.png
[Beautiful mountain landscape]
Captured during golden hour in the Rocky Mountains.
!!!

    Multiple Formats

    !!!
modern-image.webp
[WebP format image]
Takes advantage of modern compression.
!!!

!!!
vector-icon.svg
[SVG icon]
Scalable vector graphics.
!!!

    Output Examples

    Production Build

    <figure>
  <p>Alt text for accessibility</p>
  <picture>
    <source srcset="/images/photo-480w.webp 480w, /images/photo-768w.webp 768w" 
            sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw" 
            type="image/webp">
    <img src="/images/photo.jpg" 
         srcset="/images/photo-480w.jpg 480w, /images/photo-768w.jpg 768w" 
         sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw" 
         alt="Alt text for accessibility" 
         loading="lazy">
  </picture>
  <figcaption>This is the caption that appears below the image.</figcaption>
</figure>

    Development Mode

    <figure>
  <p>Alt text for accessibility</p>
  <img src="/photo.jpg" alt="Alt text for accessibility" loading="lazy" />
  <figcaption>This is the caption that appears below the image.</figcaption>
</figure>

    Dependencies Added

    • sharp: ^0.33.5 - High-performance image processing
    • vite-imagetools: ^7.1.0 - Vite integration for image optimization

    Testing

    Parser Tests (tests/parser/blocks.test.js)

    • ✅ Multiple image format detection
    • ✅ Image with description and caption parsing
    • ✅ Image with metadata parsing
    • ✅ Video format distinction

    Renderer Tests (tests/renderer/blocks.test.js)

    • ✅ Dev mode rendering
    • ✅ Optimized image rendering with simple paths
    • ✅ Optimized image rendering with picture elements
    • ✅ Handling of missing descriptions/captions

    Integration Tests (tests/e2e.test.js)

    • ✅ End-to-end image processing in dev mode
    • ✅ Proper HTML generation
    • ✅ File resolution and path handling

    Scripts Added

    • test:once: Runs tests without watch mode for CI/iteration
    • test: Runs tests in watch mode (original behavior)

    Performance Characteristics

    Development Mode

    • Fast: No image processing, direct file serving
    • Simple: Standard <img> tags
    • Immediate: Changes reflect instantly

    Production Mode

    • Optimized: Multiple formats and sizes generated
    • Responsive: Proper srcset and sizes attributes
    • Efficient: WebP primary with JPG fallback
    • Progressive: Lazy loading by default

    Error Handling

    • Missing Files: Warns but continues build, falls back to original path
    • Corrupt Images: Graceful degradation to simple <img> tag
    • Processing Errors: Logs warnings, uses fallback rendering

    Future Enhancements

    Potential areas for future improvement:

    • AVIF format support (newer than WebP)
    • Blur placeholder generation
    • Art direction support (different crops for different screen sizes)
    • Integration with CDN/external image services
    • Automatic format detection from browser capabilities

    Conclusion

    The image embedding functionality is fully implemented, tested, and working correctly. It provides a seamless authoring experience with the requested !!! image.png !!! syntax while delivering optimized, responsive images in production builds.