Building an optimized site¶
Built-in optimize plugin ¶
Sponsors only · insiders-4.29.0 · Plugin · Experimental
The built-in optimize plugin automatically identifies and optimizes all media files as part of the build using compression and conversion techniques. Add the following lines to
- Please ensure that all dependencies for image processing are installed, or the plugin will not work properly.
If you need to be able to build your documentation with and without Insiders, please refer to the built-in plugins section to learn how shared configurations help to achieve this.
The following configuration options are available:
true– This option specifies whether the plugin is enabled when building your project. If you want to speed up local builds, you can use an environment variable:
Default: number of CPUs – This option specifies how many CPUs the plugin is allowed to use when optimizing media files. With more CPUs, the plugin can do more work in the same time, thus complete optimization faster. Concurrent processing can be disabled with:
Technical documentation often includes screenshots or diagrams, both of which are prime candidates for compression. The built-in optimize plugin allows to automatically compress images using pngquant (for PNGs), and Pillow (for JPGs).
The following configuration options are available for optimization:
true– This option specifies whether the plugin should optimize PNG files using pngquant, which must be installed on the system. PNG optimization can be disabled with:
[1,10]– This option specifies the speed/quality tradeoff that pngquant applies when compressing. The lower the number, the more time will be spent optimizing:
A factor of
10has 5% lower quality, but is 8x faster than the default
true– This option specifies whether pngquant should remove all non-optional metadata that is not necessary for rendering images in a browser:
true– This option specifies whether the plugin should optimize JPG files using Pillow, a Python image processing library. JPG optimization can be disabled with:
[0,100]– This option specifies the image quality that Pillow uses when compressing. If the images look blurry, it's a good idea to tune and change this setting:
true– This option specifies whether Pillow should use progressive encoding (faster rendering) when compressing JPGs. Progressive encoding can be disabled with:
The built-in optimize plugin implements an intelligent caching mechanism, ensuring that media files are only pushed through the optimization pipeline when their contents change. If you swap out or update an image, the plugin will detect it and update the optimized version.
The following configuration options are available for caching:
true– This option specifies whether the plugin queries its cache for an existing artifact before starting an optimization job. It's normally not necessary to change this setting, except for when debugging the plugin itself. Caching can be disabled with:
.cache/plugins/optimize– This option specifies the file system location of the plugin's cache. It's normally not necessary to change this setting, except for when debugging the plugin itself. The cache directory can be changed with:
By default, all built-in plugins that implement caching will create a
.cachedirectory in the same folder your
mkdocs.ymlresides, and create subfolders to not interfere with each other. If you use multiple instances of this plugin, it could be necessary to change this setting.