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.
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:
The privacy plugin makes it easy to use unoptimized external assets, passing them to the optimize plugin before copying them to the
External media files can be automatically downloaded and optimized
The offline plugin adds support for building offline-capable documentation, so you can distribute the
sitedirectory as a
.zipfile that can be downloaded.
Your documentation can be distributed as a smaller
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:
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.
The following settings are available:
This configuration enables the plugin only during continuous integration (CI).
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:
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
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:
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:
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:
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.
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
The following settings are available for optimization:
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:
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:
A factor of
10 has 5% lower quality, but is 8x faster than the default
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:
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:
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:
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:
This configuration enables optimization for all media files that are contained in the
screenshots folder and its subfolders inside the
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:
This configuration disables optimization for all media files that are contained in the
vendor folder and its subfolders inside the
The following settings are available for reporting:
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:
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: