Built-in optimize plugin¶

The optimize plugin automatically identifies and optimizes all media files when building your project by using common compression and conversion techniques. As a result, your site loads significantly faster and yields better rankings in search engines.

Sponsors only – this plugin is currently reserved to our awesome sponsors.

Objective¶

How it works¶

The plugin scans the docs directory for media files and assets, optimizing them automatically in order to reduce the final size of the site directory. This leads to faster loading times as you ship less bytes to your users, as well as a smaller download for offline-capable documentation.

Optimized images are intelligently cached, which is why the plugin will only optimize media files that changed since the last build. This makes it possible to swap out or update images, without having to worry about optimizing them, or even worse, forgetting to do so.

In order to optimize media files, a few dependencies need to be available on your system.

When to use it¶

It's generally recommended to use the plugin, as media files are optimized automatically without the need for intervention, ensuring that your site loads as fast as possible. Optimized media files are one of the key components for a high and consistent ranking in search engines.

Additionally, the plugin can be combined with other built-in plugins that Material for MkDocs offers, in order to create sophisticated build pipelines tailored to your project:

Configuration¶

insiders-4.29.0 optimize – built-in

As with all built-in plugins, getting started with the optimize plugin is straightforward. Just add the following lines to mkdocs.yml, and observe how media files are optimized automatically:

plugins:
  - optimize

The optimize plugin is built into Material for MkDocs and doesn't need to be installed.

However, in order to optimize all media files, it's necessary to install the dependencies for image processing, if they're not already available on your system. The linked guide includes instructions for several operating systems and mentions some alternative environments.

General¶

The following settings are available:

enabled¶

insiders-4.29.0 true

Use this setting to enable or disable the plugin when building your project. If you want to disable the plugin, e.g., for local builds, you can use an environment variable in mkdocs.yml:

plugins:
  - optimize:
      enabled: !ENV [CI, false]

This configuration enables the plugin only during continuous integration (CI).

concurrency¶

insiders-4.29.0 available CPUs - 1

With more CPUs available, the plugin can do more work in parallel, and thus complete media file optimization faster. If you want to disable concurrent processing completely, use:

plugins:
  - optimize:
      concurrency: 1

By default, the plugin uses all available CPUs - 1 with a minimum of 1.

Caching¶

The plugin implements an intelligent caching mechanism, ensuring that a media file or asset is only passed through the optimization pipeline when its contents change. If you swap out or update an image, the plugin detects it and updates the optimized version of the media file.

The following settings are available for caching:

cache¶

insiders-4.29.0 true

Use this setting to instruct the plugin to bypass the cache, in order to re-optimize all media files, even though the cache may not be stale. It's normally not necessary to specify this setting, except for when debugging the plugin itself. Caching can be disabled with:

plugins:
  - optimize:
      cache: false

cache_dir¶

insiders-4.29.0 .cache/plugin/optimize

It is normally not necessary to specify this setting, except for when you want to change the path within your root directory where media files are cached. If you want to change it, use:

plugins:
  - optimize:
      cache_dir: my/custom/dir

If you're using multiple instances of the plugin, it can be a good idea to set different cache directories for both instances, so that they don't interfere with each other.

Optimization¶

Documentation often makes use of screenshots or diagrams for better visualization of things, both of which are prime candidates for optimization. The plugin automatically optimizes images using pngquant for .png files, and Pillow for .jpg files.

The following settings are available for optimization:

optimize¶

insiders-4.41.0 true

Use this setting to enable or disable media file optimization. Currently, the plugin's sole purpose is to optimize media files, so it's equivalent to the enabled setting, but in the near future, other features might be added. If you want to disable optimization, use:

plugins:
  - optimize:
      optimize: false

optimize_png¶

insiders-4.29.0 true

Use this setting to enable or disable the optimization of .png files. It's normally not necessary to specify this setting, but if you want to disable the optimization of .png files, use:

plugins:
  - optimize:
      optimize_png: false

optimize_png_speed¶

insiders-4.29.0 3 of 1-10

Use this setting to specify the speed/quality tradeoff that pngquant applies when optimizing .png files. The lower the number, the more aggressively pngquant will try to optimize:

plugins:
  - optimize:
      optimize_png_speed: 1

plugins:
  - optimize:
      optimize_png_speed: 10

A factor of 10 has 5% lower quality, but is 8x faster than the default 3.

optimize_png_strip¶

insiders-4.29.0 true

Use this setting to specify whether pngquant should strip optional metadata from .png files that are not required to display the image, e.g., EXIF. If you want to preserve metadata, use:

plugins:
  - optimize:
      optimize_png_strip: false

optimize_jpg¶

insiders-4.29.0 true

Use this setting to enable or disable the optimization of .jpg files. It's normally not necessary to specify this setting, but if you want to disable the optimization of .jpg files, use:

plugins:
  - optimize:
      optimize_jpg: false

optimize_jpg_quality¶

insiders-4.29.0 60 of 0-100

Use this setting to specify the image quality that Pillow applies when optimizing .jpg files. If the images look blurry, it's a good idea to fine-tune and change this setting:

plugins:
  - optimize:
      optimize_jpg_quality: 75

optimize_jpg_progressive¶

insiders-4.29.0 true

Use this setting to specify whether Pillow should use progressive encoding when optimizing .jpg files, rendering faster on slow connections. If you want to disable progressive encoding, use:

plugins:
  - optimize:
      optimize_jpg_progressive: false

optimize_include¶

insiders-4.41.0

Use this setting to enable media file optimization for specific directories of your project, e.g., when using multiple instances of the plugin to optimize media files differently:

plugins:
  - optimize:
      optimize_include:
        - screenshots/*

This configuration enables optimization for all media files that are contained in the screenshots folder and its subfolders inside the docs directory.

optimize_exclude¶

insiders-4.41.0

Use this setting to disable media file optimization for specific directories of your project, e.g., when using multiple instances of the plugin to optimize media files differently:

plugins:
  - social:
      optimize_exclude:
        - vendor/*

This configuration disables optimization for all media files that are contained in the vendor folder and its subfolders inside the docs directory.

Reporting¶

The following settings are available for reporting:

print_gain¶

insiders-4.29.0 true

Use this setting to control whether the plugin should print the number of bytes gained after optimizing each file. If you want to disable this behavior, use:

plugins:
  - optimize:
      print_gain: false

print_gain_summary¶

insiders-4.29.0 true

Use this setting to control whether the plugin should print the total number of bytes gained after optimizing all files. If you want to disable this behavior, use:

plugins:
  - optimize:
      print_gain_summary: false