Built-in privacy plugin¶
The privacy plugin offers a streamlined solution for automatically self-hosting external assets. With just a single line of configuration, the plugin can automatically identify and download external assets, making GDPR compliance as effortless as it can possibly be.
How it works¶
The plugin scans the generated HTML for external assets, i.e., scripts, style sheets, images, and web fonts, downloads them, stores them in the
site directory and replaces all references with links to the downloaded copies for effortless self-hosting. For example:
This external script is downloaded, and the link is replaced with:
Of course, scripts and style sheets can reference further external assets, which is why this process is repeated recursively until no further external assets are detected:
- Scripts are scanned for further scripts, style sheets and JSON files
- Style sheets are scanned for images and web fonts
Additionally, hints like
preconnect, used to reduce latency when requesting external assets, are removed from the output, as they're not necessary when self-hosting. After the plugin has done it's work, your project will be free of requests to external services.
There are some limitations.
When to use it¶
The plugin was developed to make compliance with the 2018 European General Data Protection Regulation (GDPR) as simple as possible, while retaining the flexibility and power that Material for MkDocs offers, like for example its tight integration with Google Fonts.
But, that's only the start. For example, if your project includes a lot of images, enabling the plugin allows to move them outside of your repository, as the plugin will automatically download and store them in the
site directory when building your project.
Even more interestingly, 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:
The optimize plugin allows to optimize all downloaded external assets detected by the privacy plugin by using compression and conversion techniques.
External media files are automatically downloaded and optimized
Your documentation can work without connectivity to the internet
As with all built-in plugins, getting started with the privacy plugin is straightforward. Just add the following lines to
mkdocs.yml, and start effortlessly self-hosting external assets:
The privacy plugin is built into Material for MkDocs and doesn't need to be installed.
The following settings are available:
This configuration enables the plugin only during continuous integration (CI).
9.5.0 available CPUs - 1
With more CPUs available, the plugin can do more work in parallel, and thus complete handling of external assets faster. If you want to disable concurrent processing completely, use:
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
The plugin implements an intelligent caching mechanism, ensuring that external assets are only downloaded when they're not already contained in the cache. While the initial build might take some time, it's a good idea to use caching, as it will speed up consecutive builds.
The following settings are available for caching:
Use this setting to instruct the plugin to bypass the cache, in order to re-schedule downloads for all external assets, 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:
It is normally not necessary to specify this setting, except for when you want to change the path within your root directory where downloaded copies are cached. If you want to change it, use:
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.
The following settings are available for logging:
Use this setting to control whether the plugin should display log messages when building your site. While not being recommended, you can disable logging with:
Use this setting to control the log level that the plugin should employ when encountering errors, which requires that the
log setting is enabled. The following log levels are available:
Errors, warnings and informational messages are reported, including which assets were successfully downloaded by the plugin.
The following settings are available for external assets:
Use this setting to control whether the plugin should download external assets. If you only want the plugin to process external links, you can disable handling of external assets with:
Use this setting to control whether the plugin should downloads or only report external assets when they're encountered. If you already self-host all external assets, this setting can be used as a safety net to detect links to external assets placed by the author in pages:
It is normally not necessary to specify this setting, except for when you want to change the path within the
site directory where external assets are stored. If you want to change it, use:
This configuration stores the downloaded copies at
my/custom/dir in the
Use this setting to enable downloading of external assets for specific origins, e.g., when using multiple instances of the plugin to fine-tune processing of external assets for different origins:
Use this setting to disable downloading of external assets for specific origins, e.g., when using multiple instances of the plugin to fine-tune processing of external assets for different origins:
Giscus, which we recommend to use as a comment system, uses a technique called code-splitting to load only the code that is necessary, which is implemented via relative URLs. Giscus can be self-hosted as well.
The following settings are available for external links:
Use this setting to instruct the plugin to parse and process external links to annotate them for improved security, or to automatically add additional attributes to external links. If you want to disable processing of external links, use:
Use this setting to specify additional attributes that should be added to external links, for example, to add
target="_blank" to all external links so they open in a new tab:
It is normally not recommended to change this setting, as it will automatically annotate external links that open in a new window with
rel="noopener" for improved security:
Dynamically created URLs as part of scripts are not detected, and thus cannot be downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
Instead, always use fully qualified URLs: