内置隐私插件¶

¥Built-in privacy plugin¶

隐私插件提供了一个精简的解决方案，用于自动托管外部资产。只需一行配置，该插件即可自动识别并下载外部资产，从而尽可能轻松地实现 GDPR 合规。

¥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¶

该插件会扫描生成的 HTML 文件中是否存在外部资源（例如脚本、样式表、图片和 Web 字体），然后下载并存储到网站目录中，并将所有引用替换为下载副本的链接，从而轻松实现自托管。例如：

¥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:

扫描脚本以获取更多脚本、样式表和 JSON 文件
¥Scripts are scanned for further scripts, style sheets and JSON files
扫描样式表以查找图像和 Web 字体
¥Style sheets are scanned for images and web fonts

此外，用于减少请求外部资源时延迟的preconnect等提示已从输出中移除，因为在自托管模式下它们并非必需。插件完成工作后，您的项目将不再需要对外部服务发出请求。

¥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 its work, your project will be free of requests to external services.

有一些限制。

¥There are some limitations.

何时使用¶

¥When to use it¶

该插件的开发是为了尽可能简单地遵守 2018 年欧洲通用数据保护条例(GDPR)，同时保留 Material for MkDocs 提供的灵活性和强大功能，例如与Google Fonts 的紧密集成。

¥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.

更有趣的是，该插件可以与 Material for MkDocs 提供的其他内置插件结合使用，以创建适合您项目的复杂构建管道：

¥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:

内置优化插件优化插件允许使用压缩和转换技术优化隐私插件检测到的所有已下载的外部资产。外部媒体文件会自动下载并优化
内置离线插件离线插件增加了对构建离线文档的支持，因此您可以将站点目录分发为可下载的.zip文件。您的文档无需连接互联网即可运行。

配置¶

¥Configuration¶

9.5.0隐私 – 内置

¥ Built-in optimize plugin

与所有内置插件一样，隐私插件的使用非常简单。只需将以下几行添加到mkdocs.yml ，即可轻松开始自行托管外部资产：

¥The optimize plugin allows to optimize all downloaded external assets detected by the privacy plugin by using compression and conversion techniques.

plugins:
  - privacy

隐私插件内置于 Material for MkDocs 中，无需安装。

¥External media files are automatically downloaded and optimized

一般的¶

¥General¶

可用的设置如下：

¥ Built-in offline plugin

`enabled`¶

¥enabled¶

9.5.0真

¥The offline plugin adds support for building offline-capable documentation, so you can distribute the site directory as a .zip file that can be downloaded.

使用此设置在构建项目时启用或禁用插件。如果要禁用该插件（例如，对于本地构建），可以在mkdocs.yml中使用环境变量：

¥Your documentation can work without connectivity to the internet

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

此配置仅在持续集成（CI）期间启用插件。

¥9.5.0 privacy – built-in

`concurrency`¶

¥concurrency¶

9.5.0可用 CPU - 1

¥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:

有了更多可用的 CPU，插件可以并行执行更多工作，从而更快地完成外部资源的处理。如果要完全禁用并发处理，请使用：

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

plugins:
  - privacy:
      concurrency: 1

默认情况下，该插件使用所有可用的 CPU - 1，最少 1 个。

¥The following settings are available:

缓存¶

¥Caching¶

该插件实现了智能缓存机制，确保仅当外部资源尚未包含在缓存中时才会下载。虽然初始构建可能需要一些时间，但使用缓存是个好主意，因为它可以加快后续构建的速度。

¥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:

`cache`¶

¥cache¶

9.5.0真

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

使用此设置可指示插件绕过缓存，以便重新安排所有外部资源的下载，即使缓存可能尚未过期。通常无需指定此设置，除非调试插件本身。可以使用以下命令禁用缓存：

¥9.5.0 available CPUs - 1

plugins:
  - privacy:
      cache: false

`cache_dir`¶

¥cache_dir¶

9.5.0 .缓存/插件/隐私

¥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.

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

如果您使用插件的多个实例，最好为两个实例设置不同的缓存目录，这样它们就不会互相干扰。

¥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.

日志记录¶

¥Logging¶

以下设置可用于日志记录：

¥The following settings are available for caching:

`log`¶

¥log¶

insiders-4.50.0真实

¥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:
      log: false

`log_level`¶

¥log_level¶

insiders-4.50.0信息

¥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:

errorwarninfodebug

plugins:
  - privacy:
      log_level: error

仅报告错误。

¥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.

plugins:
  - privacy:
      log_level: warn

报告错误和警告，以严格模式终止构建。这包括在 Windows 系统上由于权限不足而无法创建符号链接时发出的警告 ( #6550 )。

¥The following settings are available for logging:

plugins:
  - privacy:
      log_level: info

报告错误、警告和信息消息，包括插件成功下载了哪些资产。

¥ insiders-4.50.0 true

plugins:
  - privacy:
      log_level: debug

当且仅当 MkDocs 使用--verbose标志启动时，才会报告所有消息，包括调试消息。请注意，这将打印大量消息，并且仅用于调试。

¥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:

外部资产¶

¥External assets¶

以下设置适用于外部资产：

¥ insiders-4.50.0 info

`assets`¶

¥assets¶

9.5.0真

¥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:

使用此设置可控制插件是否下载外部资源。如果您只希望插件处理外部链接，则可以使用以下命令禁用对外部资源的处理：

¥Only errors are reported.

plugins:
  - privacy:
      assets: false

`assets_fetch`¶

¥assets_fetch¶

9.5.0真

¥Errors and warnings are reported, terminating the build in strict mode. This includes warnings when symlinks cannot be created due to a lack of permissions on Windows systems (#6550).

使用此设置可控制插件在遇到外部资源时是否下载或仅报告。如果您已自行托管所有外部资源，则可使用此设置作为安全网，以检测作者在页面中放置的外部资源链接：

¥Errors, warnings and informational messages are reported, including which assets were successfully downloaded by the plugin.

plugins:
  - privacy:
      assets_fetch: true

`assets_fetch_dir`¶

¥assets_fetch_dir¶

9.5.0资产/外部

¥All messages are reported, including debug messages, if and only if MkDocs was started with the --verbose flag. Note that this will print a lot of messages and is only useful for debugging.

通常情况下，无需指定此设置，除非您想要更改站点目录中存储外部资产的路径。如果您需要更改，请使用：

¥The following settings are available for external assets:

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

此配置将下载的副本存储在站点目录的my/custom/dir中。

¥9.5.0 true

`assets_include`¶

¥assets_include¶

insiders-4.37.0

¥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:

使用此设置可以启用特定来源的外部资产下载，例如，当使用插件的多个实例来微调不同来源的外部资产处理时：

¥9.5.0 true

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

`assets_exclude`¶

¥assets_exclude¶

insiders-4.37.0

¥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:

使用此设置可以禁用特定来源的外部资产的下载，例如，当使用插件的多个实例来微调不同来源的外部资产的处理时：

¥9.5.0 assets/external

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

MathJax通过相对 URL 加载用于排版数学内容的 Web 字体，因此无法由隐私插件自动捆绑。MathJax可以自托管。我们推荐使用Giscus作为评论系统，它使用一种称为代码拆分的技术来仅加载必要的代码，该技术通过相对 URL 实现。Giscus 也可以自托管。

外部链接¶

¥External links¶

外部链接可以进行以下设置：

¥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:

`links`¶

¥links¶

insiders-4.37.0真实

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

使用此设置可指示插件解析和处理外部链接，以便对其进行注释以提高安全性，或自动向外部链接添加其他属性。如果要禁用外部链接的处理，请使用：

¥ insiders-4.37.0

plugins:
  - privacy:
      links: false

`links_attr_map`¶

¥links_attr_map¶

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:

使用此设置可以指定应添加到外部链接的附加属性，例如，向所有外部链接添加target="_blank"以便它们在新选项卡中打开：

¥ insiders-4.37.0

plugins:
  - privacy:
      links_attr_map:
        target: _blank

`links_noopener`¶

¥links_noopener¶

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:

通常不建议更改此设置，因为它会自动使用rel="noopener"注释在新窗口中打开的外部链接，以提高安全性：

¥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.

plugins:
  - privacy:
      links_noopener: true

限制¶

¥Limitations¶

动态 URL¶

¥Dynamic URLs¶

由于插件本身不执行脚本，因此脚本中动态创建的 URL 不会被检测到，因此无法自动下载。它只检测完整 URL 并进行下载和替换。简而言之，请勿这样做：

¥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.

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

相反，请始终使用完全限定的 URL：

¥The following settings are available for external links:

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

嵌入式 HTML¶

¥Embedded HTML¶

默认情况下，嵌入的 HTML 文件（例如 iframe 中的文件）不会扫描外部资产。这是 MkDocs 的一个限制，因为它将.html文件视为模板，必须在extra_templates下明确列出。因此，要自行托管嵌入 HTML 文件的外部资产：

¥ insiders-4.37.0 true

extra_templates:
  - iframe.html

请注意， iframe.html的路径是相对于docs_dir目录的。

¥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: