diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md index ef57c53b6..89eae489c 100644 --- a/docs/publishing-your-site.md +++ b/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 `.github.io/`. [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 diff --git a/docs/setup/building-an-optimized-site.md b/docs/setup/building-an-optimized-site.md index 8503206fa..76e9e5ec9 100644 --- a/docs/setup/building-an-optimized-site.md +++ b/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 diff --git a/docs/setup/dependencies/image-processing.md b/docs/setup/dependencies/image-processing.md new file mode 100644 index 000000000..692063ba2 --- /dev/null +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 4a4ba225b..2c666057f 100755 --- a/mkdocs.yml +++ b/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