Added guide on installing image processing dependencies

Author: squidfunk

docs/publishing-your-site.md

@@ -38,6 +38,10 @@ contents:
           - uses: actions/setup-python@v4
             with:
               python-version: 3.x
+          - uses: actions/cache@v2
+            with:
+              key: ${{ github.ref }}
+              path: .cache
           - run: pip install mkdocs-material # (3)!
           - run: mkdocs gh-deploy --force
     ```
@@ -77,13 +81,21 @@ contents:
           - uses: actions/setup-python@v4
             with:
               python-version: 3.x
+          - uses: actions/cache@v2
+            with:
+              key: ${{ github.ref }}
+              path: .cache
+          - run: apt-get install pngquant # (1)!
           - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
           - run: mkdocs gh-deploy --force
     env:
-      GH_TOKEN: ${{ secrets.GH_TOKEN }} # (1)!
+      GH_TOKEN: ${{ secrets.GH_TOKEN }} # (2)!
     ```
 
-    1.  Remember to set the `GH_TOKEN` environment variable to the value of your
+    1.  This step is only necessary if you want to use the
+        [built-in optimize plugin] to automatically compress images.
+
+    2.  Remember to set the `GH_TOKEN` environment variable to the value of your
         [personal access token] when deploying [Insiders], which can be done
         using [GitHub secrets].
 
@@ -101,6 +113,7 @@ Your documentation should shortly appear at `<username>.github.io/<repository>`.
   [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
   [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
   [Insiders]: insiders/index.md
+  [built-in optimize plugin]: setup/building-an-optimized-site.md#built-in-optimize-plugin
   [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
   [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
 

docs/setup/building-an-optimized-site.md

@@ -26,18 +26,18 @@ the following lines to `mkdocs.yml`:
 
 ``` yaml
 plugins:
-  - optimize
+  - optimize # (1)!
 ```
 
+1.  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:
 
-  [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
@@ -63,8 +63,6 @@ The following configuration options are available:
           concurrency: 1
     ```
 
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
-
 #### Optimization
 
 Technical documentation often includes screenshots or diagrams, both of which
@@ -158,6 +156,10 @@ The following configuration options are available for optimization:
           optimize_jpg_progressive: false
     ```
 
+  [Insiders]: ../insiders/index.md
+  [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
+  [dependencies for image processing]: dependencies/image-processing.md
+  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
   [pngquant]: https://pngquant.org/
   [Pillow]: https://pillow.readthedocs.io/
   [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339

docs/setup/dependencies/image-processing.md

@@ -0,0 +1,112 @@
+# Image processing
+
+Material for MkDocs depends on several libraries to allow for image processing
+as part of the build pipline, including [social cards] and [image optimization].
+For this reason, a few external libraries must be installed on the host system.
+This section explains how to install them.
+
+  [social cards]: ../setting-up-social-cards.md
+  [image optimization]: ../building-an-optimized-site.md
+
+## Dependencies
+
+### 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:
+
+=== ":material-apple: macOS"
+
+    Make sure [Homebrew] is installed, which is a modern package manager for
+    macOS. Next, use the following command to install all necessary
+    dependencies:
+
+    ```
+    brew install cairo freetype libffi libjpeg libpng zlib
+    ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+    As stated in the [installation guide], the easiest way to get up and running
+    with the [Cairo Graphics] library on Windows is by installing [GTK+], since
+    it has Cairo as a dependency. You can also download and install a
+    precompiled [GTK runtime].
+
+=== ":material-linux: Linux"
+
+    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:
+
+    === ":material-ubuntu: Ubuntu"
+
+        ```
+        apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+        ```
+
+    === ":material-fedora: Fedora"
+
+        ```
+        yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
+        ```
+
+    === ":fontawesome-brands-suse: openSUSE"
+
+        ```
+        zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
+        ```
+
+The following environments come with a preinstalled version of [Cairo Graphics]:
+
+- [x] No installation needed in [Docker image]
+- [x] No installation needed in [GitHub Actions] (Ubuntu)
+
+  [Cairo Graphics]: https://www.cairographics.org/
+  [Pillow]: https://pillow.readthedocs.io/
+  [CairoSVG]: https://cairosvg.org/
+  [Homebrew]: https://brew.sh/
+  [installation guide]: https://www.cairographics.org/download/
+  [GTK+]: https://www.gtk.org/docs/installations/windows/
+  [GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
+  [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+  [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+
+### 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:
+
+=== ":material-apple: macOS"
+
+    Make sure [Homebrew] is installed, which is a modern package manager for
+    macOS. Next, use the following command to install all necessary
+    dependencies:
+
+    ```
+    brew install pngquant
+    ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+    Installing [pngquant] on Windows is a little more involved. The 
+    [pngquant-winbuild] repository contains a guide on how to set up an 
+    environment for building [pngquant] on Windows.
+
+=== ":material-linux: Linux"
+
+    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:
+
+    ```
+    apt-get install pngquant
+    ```
+
+    The same is true for `yum` and `zypper`.
+
+  [pngquant]: https://pngquant.org/
+  [built-in optimize plugin]: ../building-an-optimized-site.md#built-in-optimize-plugin
+  [pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild

mkdocs.yml

@@ -186,6 +186,8 @@ nav:
       - setup/extensions/index.md
       - Python Markdown: setup/extensions/python-markdown.md
       - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
+    - Dependencies:
+      - setup/dependencies/image-processing.md
   - Reference:
     - reference/index.md
     - Admonitions: reference/admonitions.md