图像处理¶
¥Image processing¶
一些内置插件依赖于外部库来实现高效的图像处理，其中最引人注目的是用于生成社交卡片的社交插件，以及用于应用图像优化的优化插件。本指南介绍如何在不同环境中安装这些库。
¥Some of the built-in plugins depend on external libraries for efficient image processing, most notably the social plugin to generate social cards, and the optimize plugin for applying image optimization. This guide explains how to install those libraries in different environments.
依赖项¶
¥Dependencies¶
用于图像处理的库完全是可选的，只有当您要使用社交插件或优化插件时才需要安装。这些库列在imaging附加组件下：
¥The libraries for image processing are entirely optional, and only need to be installed if you want to use the social plugin or the optimize plugin. The libraries are listed under the imaging extra:
这将安装以下软件包的兼容版本：
¥This will install compatible versions of the following packages:
开罗图形¶
¥Cairo Graphics¶
Cairo Graphics是一个图形库，是Pillow的依赖项，Material for MkDocs 利用它生成社交卡片并执行图像优化。请参阅以下部分，了解如何在系统上安装Cairo Graphics及其依赖项：
¥Cairo Graphics is a graphics library and dependency of Pillow, which Material for MkDocs makes use of for generating social cards and performing image optimization. See the following section which explains how to install Cairo Graphics and its dependencies on your system:
确保已安装Homebrew ，它是 macOS 的现代软件包管理器。接下来，使用以下命令安装所有必需的依赖项：
¥Make sure Homebrew is installed, which is a modern package manager for macOS. Next, use the following command to install all necessary dependencies:
启动并运行Cairo 图形库最简单的方法是通过MSYS2安装它，MSYS2 是一个适用于 Windows 的软件发行版和构建平台。在 MSYS2 shell 中运行以下命令：
¥The easiest way to get up and running with the Cairo Graphics library is by installing it via MSYS2, which is a software distribution and building platform for Windows. Run the following command inside of a MSYS2 shell:
MSYS2 在多个不同的环境中提供了 Cairo Graphics 库。上述命令使用UCRT64环境，这是 MSYS2 开发人员推荐的。
¥MSYS2 provides the Cairo Graphics library in several different environments. The above command uses the UCRT64 environment, as recommended by the MSYS2 developers.
Linux 上有几个软件包管理器，每个发行版的可用性各不相同。安装指南介绍了如何为您的发行版安装Cairo Graphics库：
¥There are several package managers for Linux with varying availability per distribution. The installation guide explains how to install the Cairo Graphics library for your distribution:
以下环境附带预安装的Cairo Graphics版本：
¥The following environments come with a preinstalled version of Cairo Graphics:
Docker 镜像中无需安装
GitHub Actions （Ubuntu）中无需安装
pngquant¶
¥pngquant¶
pngquant是一个优秀的有损 PNG 压缩库，并且是内置优化插件的直接依赖。请参阅以下部分，了解如何安装pngquant系统：
¥pngquant is an excellent library for lossy PNG compression, and a direct dependency of the built-in optimize plugin. See the following section which explains how to install pngquant system:
确保已安装Homebrew ，它是 macOS 的现代软件包管理器。接下来，使用以下命令安装所有必需的依赖项：
¥Make sure Homebrew is installed, which is a modern package manager for macOS. Next, use the following command to install all necessary dependencies:
获取pngquant最简单的方法是通过MSYS2安装它，MSYS2 是一个适用于 Windows 的软件分发和构建平台。在 MSYS2 shell 中运行以下命令：
¥The easiest way to get pngquant is by installing it via MSYS2, which is a software distribution and building platform for Windows. Run the following command inside of a MSYS2 shell:
所有流行的 Linux 发行版，无论使用哪种软件包管理器，都应该允许使用捆绑的软件包管理器安装pngquant 。例如，在 Ubuntu 上，可以使用以下命令安装pngquant ：
¥All popular Linux distributions, regardless of package manager, should allow to install pngquant with the bundled package manager. For example, on Ubuntu, pngquant can be installed with:
yum和zypper也是如此。
¥The same is true for yum and zypper.
以下环境附带预安装的pngquant版本：
¥The following environments come with a preinstalled version of pngquant:
Docker 镜像中无需安装
故障排除¶
¥Troubleshooting¶
未找到开罗图书馆¶
¥Cairo library was not found¶
按照上述安装指南操作后，您可能仍然会遇到以下错误：
¥After following the installation guide above it may happen that you still get the following error:
no library called "cairo-2" was found
no library called "cairo" was found
no library called "libcairo-2" was found
cannot load library 'libcairo.so.2': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
cannot load library 'libcairo.2.dylib': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
cannot load library 'libcairo-2.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
这意味着cairosvg包已安装，但底层cairocffi依赖项找不到已安装的库。根据操作系统的不同，库查找过程会有所不同：
¥This means that the cairosvg package was installed, but the underlying cairocffi dependency couldn't find the installed library. Depending on the operating system the library lookup process is different:
提示
¥Tip
在继续操作之前，请记住完全重启所有打开的终端窗口及其宿主程序（例如 IDE），以重新加载在安装过程中更改的环境变量。这可能是快速修复的方法。
¥Before proceeding remember to fully restart any open Terminal windows, and their parent hosts like IDEs to reload any environmental variables, which were altered during the installation process. This might be the quick fix.
在 macOS 上，库查找会检查dyld中定义的路径。此外，每个库name还会以三种格式进行检查： libname.dylib 、 name.dylib和name.framework/name 。
¥On macOS the library lookup checks inside paths defined in dyld. Additionally each library name is checked in three variants with the libname.dylib, name.dylib and name.framework/name format.
Homebrew应该设置每个需要的变量以指向已安装的库目录，但如果没有发生这种情况，您可以使用下面的调试脚本来查看查找了哪些路径。
¥Homebrew should set every needed variable to point at the installed library directory, but if that didn't happen, you can use the debug script below to see what paths are looked up.
一种已知的解决方法是在运行 MkDocs 之前直接添加 Homebrew lib 路径：
¥A known workaround is to add the Homebrew lib path directly before running MkDocs:
查看cairo-lookup-macos.py的源代码
¥View source code of cairo-lookup-macos.py
在 Windows 上，库查找会检查环境变量PATH中定义的路径。此外，每个库name都会以name和name.dll两种格式进行检查。
¥On Windows the library lookup checks inside the paths defined in the environmental PATH variable. Additionally each library name is checked in two variants with the name and name.dll format.
使用上述命令安装软件包的MSYS2的UCRT64环境的默认二进制文件和共享库路径为：
¥The default binary and shared library path for the UCRT64 environment of MSYS2, in which the packages were installed using the above commands, is:
使用下面的调试脚本检查路径是否包含。如果没有，则：
¥Use the debug script below to check if the path is included. If it isn't then:
按Win+R 。
¥Press Win+R.
运行
SystemPropertiesAdvanced小程序。¥Run the
SystemPropertiesAdvancedapplet.选择底部的“环境变量”。
¥Select "Environmental Variables" at the bottom.
将上述目录的完整路径添加到
Path变量中。¥Add the whole path to the above directory to your
Pathvariable.在所有打开的窗口中单击“确定”以应用更改。
¥Click OK on all open windows to apply changes.
完全重新启动所有打开的终端窗口及其父主机，如 IDE。
¥Fully restart any open Terminal windows and their parent hosts like IDEs.
查看cairo-lookup-windows.py的源代码
¥View source code of cairo-lookup-windows.py
在 Linux 上，库查找可能有很大差异，并且取决于安装的发行版。对于已测试的 Ubuntu 和 Manjaro 系统，Python 会运行 shell 命令来检查ldconfig 、 gcc / cc编译器和ld中可用的库。
¥On Linux the library lookup can differ greatly and is dependent from the installed distribution. For tested Ubuntu and Manjaro systems Python runs shell commands to check which libraries are available in ldconfig, in the gcc/cc compiler, and in ld.
您可以使用包含libcairo.so等的库目录的绝对路径来扩展LD_LIBRARY_PATH环境变量。在 MkDocs 之前直接运行此命令：
¥You can extend the LD_LIBRARY_PATH environmental variable with an absolute path to a library directory containing libcairo.so etc. Run this directly before MkDocs:
您也可以修改/etc/ld.so.conf文件。
¥You can also modify the /etc/ld.so.conf file.
下面的 Python 脚本显示了正在运行哪个函数来查找已安装的库。您可以检查源代码，了解在库查找期间系统上执行了哪些具体命令。
¥The Python script below shows, which function is being run to find installed libraries. You can check the source to find out what specific commands are executed on your system during library lookup.
查看cairo-lookup-linux.py的源代码
¥View source code of cairo-lookup-linux.py