11 KiB
| title | icon |
|---|---|
| Built-in optimize plugin | material/rabbit |
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.
Objective
How it works
The plugin scans the [docs directory][mkdocs.docs_dir] for media files and
assets, optimizing them automatically in order to reduce the final size of the
[site directory][mkdocs.site_dir]. 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:
-
:material-shield-account: Built-in privacy plugin
The privacy plugin makes it easy to use unoptimized external assets, passing them to the optimize plugin before copying them to the [
sitedirectory] [mkdocs.site_dir].
External media files can be automatically downloaded and optimized
-
:material-connection: Built-in offline plugin
The offline plugin adds support for building offline-capable documentation, so you can distribute the [
sitedirectory][mkdocs.site_dir] as a.zipfile that can be downloaded.
Your documentation can be distributed as a smaller
.zipdownload
Configuration
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:
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][mkdocs.env] in mkdocs.yml:
plugins:
- optimize:
enabled: !ENV [CI, false]
This configuration enables the plugin only during continuous integration (CI).
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:
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
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:
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][config.enabled] setting, but in the near future, other features
might be added. If you want to disable optimization, use:
plugins:
- optimize:
optimize: false
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
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:
=== "Slower smaller"
``` yaml
plugins:
- optimize:
optimize_png_speed: 1
```
=== "Faster larger"
``` yaml
plugins:
- optimize:
optimize_png_speed: 10
```
A factor of 10 has 5% lower quality, but is 8x faster than the default 3.
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
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
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
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
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]
[mkdocs.docs_dir].
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]
[mkdocs.docs_dir].
Reporting
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:
plugins:
- optimize:
print_gain: false
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