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.

Objective¶

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:

<script src="https://example.com/script.js"></script>

This external script is downloaded, and the link is replaced with:

<script src="assets/external/example.com/script.js"></script>

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:

Configuration¶

9.5.0 privacy – built-in

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:

plugins:
  - privacy

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

General¶

The following settings are available:

enabled¶

9.5.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:

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

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

concurrency¶

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:

plugins:
  - privacy:
      concurrency: 1

By default, the plugin uses all available CPUs - 1 with a minimum of 1.

Caching¶

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:

cache¶

9.5.0 true

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:

plugins:
  - privacy:
      cache: false

cache_dir¶

9.5.0 .cache/plugin/privacy

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:

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

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.

Logging¶

The following settings are available for logging:

log¶

insiders-4.50.0 true

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:

plugins:
  - privacy:
      log: false

log_level¶

insiders-4.50.0 info

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:

plugins:
  - privacy:
      log_level: error

plugins:
  - privacy:
      log_level: warn

plugins:
  - privacy:
      log_level: info

plugins:
  - privacy:
      log_level: debug

External assets¶

The following settings are available for external assets:

assets¶

9.5.0 true

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:

plugins:
  - privacy:
      assets: false

assets_fetch¶

9.5.0 true

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:

plugins:
  - privacy:
      assets_fetch: true

assets_fetch_dir¶

9.5.0 assets/external

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:

plugins:
  - privacy:
      assets_fetch_dir: my/custom/dir

This configuration stores the downloaded copies at my/custom/dir in the site directory.

assets_include¶

insiders-4.37.0

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:

plugins:
  - privacy:
      assets_include:
        - unsplash.com/*

assets_exclude¶

insiders-4.37.0

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:

plugins:
  - privacy:
      assets_exclude: # (1)!
        - unpkg.com/mathjax@3/*
        - giscus.app/*

1. MathJax loads web fonts for typesetting of mathematical content through relative URLs, and thus cannot be automatically bundled by the privacy plugin. MathJax can be self-hosted.

   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.

External links¶

The following settings are available for external links:

links¶

insiders-4.37.0 true

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:

plugins:
  - privacy:
      links: false

links_attr_map¶

insiders-4.37.0

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:

plugins:
  - privacy:
      links_attr_map:
        target: _blank

links_noopener¶

insiders-4.37.0 true

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:

plugins:
  - privacy:
      links_noopener: true

Limitations¶

Dynamic URLs¶

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:

const host = "https://example.com"
const path = `${host}/script.js`

Instead, always use fully qualified URLs:

const url ="https://example.com/script.js"

Embedded HTML¶

By default, embedded HTML files (e.g. in iframes) are not scanned for external assets. This is a limitation of MkDocs, as it considers .html files to be templates, which must be explicitly listed under extra_templates. Thus, to self-host external assets of an embedded HTML file:

extra_templates:
  - iframe.html

Note that the path to iframe.html is relative to the docs_dir directory.