From ee703e6be460d9424dd340450f7993051eabe84c Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 21 Jan 2023 17:03:55 +0100 Subject: [PATCH] Added documentation for built-in optimize plugin --- docs/setup/building-an-optimized-site.md | 203 +++++++++++++++++++++++ docs/setup/building-for-offline-usage.md | 2 +- mkdocs.yml | 1 + 3 files changed, 205 insertions(+), 1 deletion(-) create mode 100644 docs/setup/building-an-optimized-site.md diff --git a/docs/setup/building-an-optimized-site.md b/docs/setup/building-an-optimized-site.md new file mode 100644 index 000000000..8503206fa --- /dev/null +++ b/docs/setup/building-an-optimized-site.md @@ -0,0 +1,203 @@ +--- +status: new +--- + +# Building an optimized site + +Material for MkDocs, by default, allows to build optimized sites that rank great +on search engines, load fast (even on slow networks), and work perfectly without +JavaScript. Additionally, the [built-in optimize plugin] adds support for +further useful automatic optimization techniques. + + [built-in optimize plugin]: #built-in-optimize-plugin + +## Configuration + +### Built-in optimize plugin + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.29.0][Insiders] · +:octicons-cpu-24: Plugin · +:octicons-beaker-24: 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 `mkdocs.yml`: + +``` yaml +plugins: + - optimize +``` + +> 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: + + [Insiders]: ../insiders/index.md + [built-in plugins]: ../insiders/getting-started.md#built-in-plugins + +[`enabled`](#+optimize.enabled){ #+optimize.enabled } + +: :octicons-milestone-24: Default: `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]: + + ``` yaml + plugins: + - optimize: + enabled: !ENV [CI, false] + ``` + +[`concurrency`](#+optimize.concurrency){ #+optimize.concurrency } + +: :octicons-milestone-24: 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: + + ``` yaml + plugins: + - optimize: + concurrency: 1 + ``` + + [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables + +#### Optimization + +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: + +[`optimize_png`](#+optimize.optimize_png){ #+optimize.optimize_png } + +: :octicons-milestone-24: Default: `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: + + ``` yaml + plugins: + - optimize: + optimize_png: false + ``` + +[`optimize_png_speed`](#+optimize.optimize_png_speed){ #+optimize.optimize_png_speed } + +: :octicons-milestone-24: Default: `4` of `[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: + + === "Slower small" + + ``` yaml + plugins: + - optimize: + optimize_png_speed: 1 + ``` + + === "Faster rough" + + ``` yaml + plugins: + - optimize: + optimize_png_speed: 10 + ``` + + A factor of `10` has 5% lower quality, but is 8x faster than the default `4`. + +[`optimize_png_strip`](#+optimize.optimize_png_strip){ #+optimize.optimize_png_strip } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + [pngquant] should remove all non-optional metadata that is not necessary + for rendering images in a browser: + + ``` yaml + plugins: + - optimize: + optimize_png_strip: false + ``` + +[`optimize_jpg`](#+optimize.optimize_jpg){ #+optimize.optimize_jpg } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + the plugin should optimize JPG files using [Pillow], a Python image + processing library. JPG optimization can be disabled with: + + ``` yaml + plugins: + - optimize: + optimize_jpg: false + ``` + +[`optimize_jpg_quality`](#+optimize.optimize_jpg_quality){ #+optimize.optimize_jpg_quality } + +: :octicons-milestone-24: Default: `60` of `[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: + + ``` yaml + plugins: + - optimize: + optimize_jpg_quality: 75 + ``` + +[`optimize_jpg_progressive`](#+optimize.optimize_jpg_progressive){ #+optimize.optimize_jpg_progressive } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + [Pillow] should use [progressive encoding] (faster rendering) when + compressing JPGs. Progressive encoding can be disabled with: + + ``` yaml + plugins: + - optimize: + optimize_jpg_progressive: false + ``` + + [pngquant]: https://pngquant.org/ + [Pillow]: https://pillow.readthedocs.io/ + [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339 + +#### Caching + +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: + +[`cache`](#+optimize.cache){ #+optimize.cache } + +: :octicons-milestone-24: Default: `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: + + ``` yaml + plugins: + - optimize: + cache: false + ``` + +[`cache_dir`](#+optimize.cache_dir){ #+optimize.cache_dir } + +: :octicons-milestone-24: Default: `.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: + + ``` yaml + plugins: + - optimize: + cache_dir: path/to/folder + ``` + + By default, all built-in plugins that implement caching will create a + `.cache` directory in the same folder your `mkdocs.yml` resides, 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. diff --git a/docs/setup/building-for-offline-usage.md b/docs/setup/building-for-offline-usage.md index c836d80b5..1af2e375a 100644 --- a/docs/setup/building-for-offline-usage.md +++ b/docs/setup/building-for-offline-usage.md @@ -2,7 +2,7 @@ If you want to ship your documentation together with your product, MkDocs has you covered – with support from themes, [MkDocs] allows for building -offline-capable documentation. Luckily, Material for MkDocs offers offline +offline-capable documentation. Notably, Material for MkDocs offers offline support for many of its features. [MkDocs]: https://www.mkdocs.org diff --git a/mkdocs.yml b/mkdocs.yml index 30e12a005..4a4ba225b 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -180,6 +180,7 @@ nav: - Setting up the footer: setup/setting-up-the-footer.md - Adding a git repository: setup/adding-a-git-repository.md - Adding a comment system: setup/adding-a-comment-system.md + - Building an optimized site: setup/building-an-optimized-site.md - Building for offline usage: setup/building-for-offline-usage.md - Extensions: - setup/extensions/index.md