WebP Image Support

WebP Image Support

This blog supports WebP images with automatic fallbacks to JPEG/PNG for better performance and compatibility.

What is WebP?

WebP is a modern image format that provides superior compression compared to JPEG and PNG:

How It Works

Automatic Generation (New Posts)

When you create a blog post via GitHub issues, the workflow automatically:

  1. Downloads images from the issue
  2. Optimizes JPEG/PNG images
  3. Generates WebP versions of all images
  4. Commits both versions to the repository

No manual intervention needed!

For Existing Images

Run the batch conversion script:

1

./scripts/generate-webp.sh

This will:

Using WebP Images in Posts

Use the 

1

webp-image.html
include for automatic WebP with fallback:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24







<figure class="aligncenter">


<picture>
  <source srcset="/assets/img/photo.webp" type="image/webp">
  <img src="/assets/img/photo.jpg"
       alt="Description of image"
       
       loading="lazy"
       decoding="async">
</picture>


  <figcaption>Optional caption text</figcaption>
</figure>

What it generates:

1
2
3
4

<picture>
  <source srcset="/assets/img/photo.webp" type="image/webp">
  <img src="/assets/img/photo.jpg" alt="Description" loading="lazy" decoding="async">
</picture>

Option 2: Manual Picture Element

For full control, use HTML picture element:

1
2
3
4
5
6
7

<picture>
  <source srcset="/assets/img/photo.webp" type="image/webp">
  <img src="/assets/img/photo.jpg"
       alt="Description"
       loading="lazy"
       decoding="async">
</picture>

With Captions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24







<figure class="aligncenter">


<picture>
  <source srcset="/assets/img/photo.webp" type="image/webp">
  <img src="/assets/img/photo.jpg"
       alt="Mountain landscape"
       
       loading="lazy"
       decoding="async">
</picture>


  <figcaption>Beautiful mountain view at sunset</figcaption>
</figure>

Generates:

1
2
3
4
5
6
7

<figure class="aligncenter">
  <picture>
    <source srcset="/assets/img/photo.webp" type="image/webp">
    <img src="/assets/img/photo.jpg" alt="Mountain landscape" loading="lazy">
  </picture>
  <figcaption>Beautiful mountain view at sunset</figcaption>
</figure>

Include Parameters

Parameter Required Description 
1

src
Yes Path to original image (JPEG/PNG) 
1

alt
No Alt text for accessibility 
1

class
No CSS class (e.g., 
1

aligncenter
, 
1

alignleft
)		 
1

caption
No Caption text (wraps in 
1

<figure>
)

Browser Support

Browser WebP Support
Chrome ✅ All versions
Firefox ✅ 65+
Edge ✅ All versions
Safari ✅ 14+ (iOS 14+)
Opera ✅ 32+

Fallback: Older browsers automatically use JPEG/PNG from the 

1

<img>
tag.

Performance Impact

Before WebP

After WebP

Page load improvements:

File Organization

1
2
3
4
5

assets/img/
├── photo.jpg      # Original (fallback)
├── photo.webp     # WebP version (served first)
├── banner.png     # Original (fallback)
└── banner.webp    # WebP version (served first)

Workflow Integration

The issue-to-post workflow (

1

.github/workflows/issue-to-post.yml
) automatically:

  1. Downloads images from GitHub issues
  2. Optimizes JPEG/PNG (resize, compress, strip metadata)
  3. Generates WebP versions with 
    1

    cwebp -q 85
  4. Commits both original and WebP versions

Quality Settings

Testing

Verify WebP Support

  1. Open blog post in Chrome DevTools
  2. Network tab → Filter by “Img”
  3. Look for 
    1

    .webp
    files being loaded
  4. Check fallback in Safari 13 or older browsers

Performance Testing

1
2
3
4
5
6

# Compare file sizes
ls -lh assets/img/photo.jpg
ls -lh assets/img/photo.webp

# Test with PageSpeed Insights
https://pagespeed.web.dev/

Migration Guide

For Existing Posts

  1. Generate WebP versions: 
    1

    ./scripts/generate-webp.sh
  2. Update post images (optional - for best results):
    • Replace 
      1

      <img>
      tags with `

`

  1. Verify:
    • Check both .jpg and .webp files exist
    • Test in browser with DevTools

For New Posts

✅ No action needed! The workflow handles everything automatically.

Troubleshooting

WebP Not Loading

File Size Too Large

Generation Script Fails

1
2
3

# Install WebP tools
brew install webp          # macOS
sudo apt-get install webp  # Linux

Best Practices

  1. ✅ Always include original JPEG/PNG as fallback
  2. ✅ Use 
    1

    webp-image.html
    include for consistency
  3. ✅ Add descriptive alt text for accessibility
  4. ✅ Test in multiple browsers
  5. ✅ Run 
    1

    generate-webp.sh
    after bulk image adds

Resources