Image Processing

Images are first-class citizens in Bestatic!! Of course, it is possible to include images in your markdown files by just using the standrad ![alt text](path/to/image.jpg) syntax of markdown. However, Bestatic provides a more powerful ways to include, style, and optimize images in your markdown files.

Styling the images

Bestatic recommends using the following syntax to include images in your markdown files:

1
2

::: figure /path/to/image.png alt='alt text' someclassname
    This is an image caption. You can use **markdown formatting** here.

This will automatically convert into a figure tag with the following HTML:

1
2
3
4
5
6
7
8

<figure class="someclassname">
  <a href=" " target="_blank">
    <img src="/path/to/image.png" alt="alt text" />
  </a>
  <figcaption>
    <p>This is an image caption. You can use <b>markdown formatting</b> here.</p>
  </figcaption>
</figure>

You can now use the someclassname to access the class name of the different images. You can use that class name in your CSS to style the different images differently.

For example, in your CSS file, you can use the following syntax to style the different images differently:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

.someclassname img {
  width: 100%;
  height: 100%;
  object-fit: cover; /* or contain, or fill, or none, or scale-down */
}

.someclassname figcaption {
  text-align: center;
  font-size: 0.8em;
  color: #666;
}

Under the hood, Bestatic uses markdown-customblock figures to process the images in this way. You can read more about it in the link provided above.

Image Optimization

(New in v0.0.36) Bestatic now includes built-in image optimization capabilities that automatically convert your images to modern WebP format, significantly reducing file sizes and improving website performance. Please note that, this will increase the build time of your site, especially for sites with a lot of images of large sizes. This feature still should be considered as experimental and you should use it with caution.

Under the hood, Bestatic uses pillow library to process the images. Pillow is a powerful library for image processing and it comes pre-installed with Bestatic.

Overview

The image processor automatically:

• Converts JPEG, PNG, and GIF images to WebP format

• Optimizes image quality while reducing file size

• Automatically resizes very large images for faster processing

• Updates all references in HTML, CSS, and JS files

• Optionally keeps original images alongside converted versions

Configuration

To enable image processing, add the image_processing section to your bestatic.yaml file:

1
2
3
4

image_processing:
  enabled: true              # Enable/disable image processing
  quality: 80                # WebP quality (1-100, default: 80)
  keep_original: false       # Keep original images alongside WebP versions

Configuration Options

1. enabled: Set to true to enable image processing, false to disable. Default is false if not specified.

2. quality: WebP compression quality from 1 (lowest quality, smallest file) to 100 (highest quality, largest file). Default is 80, which provides a good balance between quality and file size.

3. keep_original: When set to true, both the original image and the WebP version are kept in the output. When false (default), only the WebP version is kept, and all references are updated.

4. include_formats: List of image file extensions to process. By default, processes .jpg, .jpeg, .png, and .gif files. You can customize this list to include only specific formats. All are enabled by default and hence you do not need to specify this.

How It Works

When you build your site with image processing enabled:

1. Image Conversion: Bestatic scans your static-content directory and theme's static directory for images matching the specified formats.

2. WebP Generation: Each image is converted to WebP format with the specified quality setting. Very large images (over 2400px in width or height) are automatically resized to improve processing speed.

3. Reference Updates: All HTML, CSS, and JavaScript files in the output directory are scanned, and image references are automatically updated to point to the WebP versions.

4. External URL Protection: Image references to external URLs (starting with http://, https://, or //) are never modified, ensuring CDN and external images remain unchanged.

Performance Considerations

The image processor includes several optimizations:

• Large Image Detection: Images over 10MB or 10 megapixels trigger warnings and use faster processing methods.

• Automatic Resizing: Images larger than 2400px in width or height are automatically downscaled while maintaining aspect ratio.

• Adaptive Encoding Speed: Larger images use faster WebP encoding methods (lower compression effort) to reduce processing time, while smaller images use better compression for optimal file size.