Skip to content

内置优化插件

¥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

该插件会扫描docs 目录中的媒体文件和资源，并自动对其进行优化，以减少站点目录的最终大小。这将缩短加载时间，因为您向用户发送的字节数更少，并且离线文档的下载量也更小。

¥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.

此外，该插件可以与 Material for MkDocs 提供的其他内置插件结合使用，以创建适合您项目的复杂构建管道：

¥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:

  • 内置隐私插件隐私插件可以轻松使用未优化的外部资产，将其传递给优化插件，然后再复制到站点目录。外部媒体文件可以自动下载和优化

  • 内置离线插件离线插件新增了构建离线文档的支持，因此您可以将站点目录以可下载的.zip文件形式分发。您的文档可以以较小的 .zip 下载文件形式分发。

配置

¥Configuration

insiders-4.29.0优化 – 内置

¥   Built-in privacy plugin

与所有内置插件一样，优化插件的使用非常简单。只需将以下几行添加到mkdocs.yml ，然后观察媒体文件如何自动优化：

¥The privacy plugin makes it easy to use unoptimized external assets, passing them to the optimize plugin before copying them to the site directory.

plugins:
  - optimize

优化插件内置于 Material for MkDocs 中，无需安装。

¥External media files can be automatically downloaded and optimized

但是，为了优化所有媒体文件，如果您的系统上尚未安装图像处理依赖项，则需要安装它们。链接的指南包含针对多个操作系统的说明，并提到了一些替代环境。

¥   Built-in offline plugin

一般的

¥General

可用的设置如下：

¥The offline plugin adds support for building offline-capable documentation, so you can distribute the site directory as a .zip file that can be downloaded.

enabled

¥enabled

insiders-4.29.0真实

¥Your documentation can be distributed as a smaller .zip download

使用此设置在构建项目时启用或禁用插件。如果要禁用该插件（例如，对于本地构建），可以在mkdocs.yml中使用环境变量：

¥ insiders-4.29.0 optimize – built-in 

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

此配置仅在持续集成（CI）期间启用插件。

¥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:

concurrency

¥concurrency

insiders-4.29.0可用 CPU - 1

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

有了更多可用的 CPU，插件就可以并行处理更多工作，从而更快地完成媒体文件优化。如果您想完全禁用并发处理，请使用：

¥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.

plugins:
  - optimize:
      concurrency: 1

默认情况下，该插件使用所有可用的 CPU - 1，最少 1 个。

¥The following settings are available:

缓存

¥Caching

该插件实现了智能缓存机制，确保媒体文件或资源仅在其内容发生变化时才会通过优化管道。如果您替换或更新了图像，插件会检测到并更新媒体文件的优化版本。

¥ 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:

cache

¥cache

insiders-4.29.0真实

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

使用此设置可指示插件绕过缓存，以便重新优化所有媒体文件，即使缓存可能尚未过期。通常无需指定此设置，除非在调试插件本身时。可以使用以下命令禁用缓存：

¥ insiders-4.29.0 available CPUs - 1

plugins:
  - optimize:
      cache: false

cache_dir

¥cache_dir

insiders-4.29.0 .cache/插件/优化

¥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.

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

如果您使用插件的多个实例，最好为两个实例设置不同的缓存目录，这样它们就不会互相干扰。

¥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.

优化

¥Optimization

文档通常会使用屏幕截图或图表来更好地呈现内容，这两者都是优化的主要对象。该插件会自动使用pngquant优化.png文件，并使用Pillow优化.jpg文件。

¥The following settings are available for caching:

以下设置可用于优化：

¥ insiders-4.29.0 true

optimize

¥optimize

insiders-4.41.0真实

¥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:

使用此设置可启用或禁用媒体文件优化。目前，该插件的唯一目的是优化媒体文件，因此它相当于启用的设置，但在不久的将来，可能会添加其他功能。如果您想禁用优化，请使用：

¥ insiders-4.29.0 .cache/plugin/optimize

plugins:
  - optimize:
      optimize: false

optimize_png

¥optimize_png

insiders-4.29.0真实

¥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:

使用此设置可启用或禁用.png文件的优化。通常无需指定此设置，但如果您想禁用.png文件的优化，请使用：

¥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.

plugins:
  - optimize:
      optimize_png: false

optimize_png_speed

¥optimize_png_speed

insiders-4.29.0 3 的 1-10

¥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.

使用此设置指定pngquant在优化.png文件时应用的速度/质量权衡。数字越低， pngquant尝试优化的力度就越大：

¥The following settings are available for optimization:

plugins:
  - optimize:
      optimize_png_speed: 1

plugins:
  - optimize:
      optimize_png_speed: 10

因子10的质量会降低 5%，但速度比默认值3快 8 倍。

¥ insiders-4.41.0 true

optimize_png_strip

¥optimize_png_strip

insiders-4.29.0真实

¥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:

使用此设置指定pngquant是否应从.png文件中删除显示图像不需要的可选元数据，例如EXIF 。如果要保留元数据，请使用：

¥ insiders-4.29.0 true

plugins:
  - optimize:
      optimize_png_strip: false

optimize_jpg

¥optimize_jpg

insiders-4.29.0真实

¥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:

使用此设置可启用或禁用.jpg文件的优化。通常无需指定此设置，但如果您想禁用.jpg文件的优化，请使用：

¥ insiders-4.29.0 3 of 1-10

plugins:
  - optimize:
      optimize_jpg: false

optimize_jpg_quality

¥optimize_jpg_quality

insiders-4.29.0 60 / 0-100

¥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:

使用此设置指定Pillow在优化.jpg文件时应用的图像质量。如果图像看起来模糊，最好微调并更改此设置：

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

plugins:
  - optimize:
      optimize_jpg_quality: 75

optimize_jpg_progressive

¥optimize_jpg_progressive

insiders-4.29.0真实

¥ insiders-4.29.0 true

使用此设置指定Pillow在优化.jpg文件时是否应使用渐进式编码，以便在慢速连接时渲染速度更快。如果要禁用渐进式编码，请使用：

¥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_jpg_progressive: false

optimize_include

¥optimize_include

insiders-4.41.0

¥ 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_include:
        - screenshots/*

此配置可对docs 目录内的screenshots文件夹及其子文件夹中包含的所有媒体文件进行优化。

¥ insiders-4.29.0 60 of 0-100

optimize_exclude

¥optimize_exclude

insiders-4.41.0

¥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:

使用此设置可以禁用项目特定目录的媒体文件优化，例如，当使用插件的多个实例以不同方式优化媒体文件时：

¥ insiders-4.29.0 true

plugins:
  - social:
      optimize_exclude:
        - vendor/*

此配置禁用docs 目录内的vendor文件夹及其子文件夹中包含的所有媒体文件的优化。

¥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:

报告

¥Reporting

以下设置可用于报告：

¥ insiders-4.41.0

print_gain

¥print_gain

insiders-4.29.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:

使用此设置可控制插件是否应打印优化每个文件后获得的字节数。如果要禁用此行为，请使用：

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

plugins:
  - optimize:
      print_gain: false

print_gain_summary

¥print_gain_summary

insiders-4.29.0真实

¥ 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:
  - optimize:
      print_gain_summary: false