内置隐私插件¶

隐私插件提供了一种简化的解决方案，用于自动自托管外部资产。只需一行配置，插件便可以自动识别和下载外部资产，使得符合GDPR的要求变得尽可能轻松。

目标¶

工作原理¶

该插件扫描生成的HTML以查找外部资产，即脚本、样式表、图像和网页字体，下载它们，将其存储在site目录中，并用下载副本的链接替换所有引用，以实现轻松的自托管。例如：

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

这个外部脚本会被下载，链接将被替换为：

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

当然，脚本和样式表可能会引用更多的外部资产，因此这个过程会递归重复，直到不再检测到外部资产为止：

• 脚本会扫描进一步的脚本、样式表和JSON文件
• 样式表会扫描图像和网页字体

此外，像preconnect这样的提示，用于在请求外部资产时减少延迟，会从输出中移除，因为在自托管时并不需要。在插件完成工作后，您的项目将不再有对外部服务的请求。

有一些限制。

何时使用¶

该插件的开发旨在使遵循2018年欧洲__通用数据保护条例__（GDPR）变得尽可能简单，同时保留Material for MkDocs所提供的灵活性和强大功能，例如与Google Fonts的紧密集成。

但这只是开始。例如，如果您的项目包含大量图像，启用该插件可以将它们移出您的代码库，因为插件会在构建您的项目时自动下载并存储它们到site目录中。

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

配置¶

9.5.0 [privacy] – built-in

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

plugins:
  - privacy

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

一般设置¶

以下设置可用：

enabled¶

9.5.0 true

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

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

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

concurrency¶

9.5.0 available CPUs - 1

可用CPU越多，插件可以并行处理的工作就越多，从而更快地完成外部资产的处理。如果您想完全禁用并发处理，请使用：

plugins:
  - privacy:
      concurrency: 1

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

缓存¶

该插件实现了一种智能缓存机制，确保仅在外部资产不在缓存中时才会下载它们。虽然初始构建可能需要一些时间，但使用缓存是个好主意，因为它会加速后续构建。

以下设置可用于缓存：

cache¶

9.5.0 true

使用此设置指示插件绕过缓存，以重新调度所有外部资产的下载，即使缓存可能并未过期。通常不需要指定此设置，除非在调试插件本身时。可以通过以下方式禁用缓存：

plugins:
  - privacy:
      cache: false

cache_dir¶

9.5.0 .cache/plugin/privacy

通常不需要指定此设置，除非您想更改下载副本缓存的根目录路径。如果您想更改它，请使用：

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

如果您使用多个实例的插件，为两个实例设置不同的缓存目录可能是个好主意，以免相互干扰。

日志记录¶

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

log¶

9.7.0 true

使用此设置控制插件在构建您的网站时是否显示日志消息。虽然不推荐，但您可以通过以下方式禁用日志记录：

plugins:
  - privacy:
      log: false

log_level¶

9.7.0 info

使用此设置控制插件在遇到错误时应使用的日志级别，这要求log设置已启用。以下日志级别可用：

plugins:
  - privacy:
      log_level: error

plugins:
  - privacy:
      log_level: warn

plugins:
  - privacy:
      log_level: info

plugins:
  - privacy:
      log_level: debug

外部资产¶

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

assets¶

9.5.0 true

使用此设置控制插件是否应下载外部资产。如果您只希望插件处理外部链接，可以通过以下方式禁用外部资产的处理：

plugins:
  - privacy:
      assets: false

assets_fetch¶

9.5.0 true

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

plugins:
  - privacy:
      assets_fetch: true

assets_fetch_dir¶

9.5.0 assets/external

通常不需要指定此设置，除非您想更改在site目录中存储外部资产的路径。如果您想更改它，请使用：

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

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

assets_include¶

9.7.0

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

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

assets_exclude¶

9.7.0

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

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

1. MathJax通过相对URL加载用于排版数学内容的网页字体，因此无法被隐私插件自动打包。MathJax可以自托管。

   Giscus，我们推荐用作评论系统，使用了一种称为代码分割的技术，仅加载必要的代码，这通过相对URL实现。[Giscus也可以自托管]。

外部链接¶

以下设置可用于外部链接：

links¶

9.7.0 true

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

plugins:
  - privacy:
      links: false

links_attr_map¶

9.7.0

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

plugins:
  - privacy:
      links_attr_map:
        target: _blank

links_noopener¶

9.7.0 true

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

plugins:
  - privacy:
      links_noopener: true

限制¶

动态URL¶

作为脚本的一部分动态创建的URL不会被检测，因此无法自动下载，因为插件不会执行脚本——它只检测用于下载和替换的完全合格URL。简而言之，不要这样做：

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

相反，始终使用完全合格的URL：

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

嵌入的HTML¶

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

extra_templates:
  - iframe.html

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