Skip to content

确保数据隐私

MkDocs的Material使遵守数据隐私法规变得非常简单，因为它提供了一个原生的cookie consent解决方案，以在设置analytics之前寻求用户的明确同意。此外，外部资产可以自动下载以进行self-hosting。

配置

8.4.0


.zip

MkDocs的Material提供了一个原生且可扩展的cookie同意表单，在向第三方发送请求之前询问用户的同意。将以下内容添加到mkdocs.yml中：

extra:
  consent:
    title: Cookie consent
    description: >- # (1)!
      我们使用cookies来识别您的重复访问和偏好，并衡量我们的文档的有效性以及用户是否找到了他们所搜索的内容。通过您的同意，您帮助我们改进我们的文档。
  1. 您可以在description中添加任意HTML标签，例如链接到您的服务条款或网站的其他部分。

以下属性可用：

title


此属性设置cookie同意的标题，该标题在表单顶部呈现，必须设置为非空字符串。

description


此属性设置cookie同意的描述，在标题下方呈现，并可以包含原始HTML（例如，指向服务条款的链接）。

cookies

此属性允许添加自定义 cookies或更改内置cookies的初始checked状态和名称。 目前，内置的cookies包括：

  • Google Analytics – analytics（默认启用）
  • GitHub – github（默认启用）

每个cookie必须接收一个唯一标识符，该标识符用作cookies映射中的键，可以设置为字符串或定义name和checked状态的映射：

extra:
  consent:
    cookies:
      analytics: 自定义名称

extra:
  consent:
    cookies:
      analytics:
        name: Google Analytics
        checked: false

extra:
  consent:
    cookies:
      analytics: Google Analytics # (1)!
      custom: 自定义cookie
  1. 如果您在cookies属性中定义了自定义cookie，则必须显式添加analytics cookie，否则将不会触发分析。

如果通过mkdocs.yml配置了Google Analytics，cookie同意将自动包含一个设置，允许用户禁用它。自定义cookies可以通过JavaScript使用。

actions

[accept, manage] 此属性定义 显示哪些按钮以及顺序，例如，允许用户接受 cookies并管理设置：

extra:
  consent:
    actions:
      - accept
      - manage # (1)!
  1. 如果actions属性中省略了manage设置按钮，则始终显示设置。

cookie同意表单包括三种类型的按钮：

  • accept – 接受所选cookies的按钮
  • reject – 拒绝所有cookies的按钮
  • manage – 管理设置的按钮

当用户首次访问您的网站时，将呈现cookie同意表单：

Cookie consent enabled

为了遵守GDPR，用户必须能够随时更改其cookie设置。这可以通过在mkdocs.yml中添加一个简单的链接到您的版权声明来完成：

copyright: >
  版权所有 © 2016 - 2024 Martin Donath –
  <a href="#__consent">更改cookie设置</a>

内置隐私插件

9.5.0
[privacy][built-in privacy plugin]

内置隐私插件在构建过程中自动识别外部资产，并下载所有资产以实现非常简单的自托管。将以下行添加到mkdocs.yml中：

plugins:
  - privacy

有关所有设置的列表，请参阅插件文档。

外部托管图像并自动优化

此选项使内置隐私插件成为一个优秀的选择，当您希望将资产（如图像）托管在您的git存储库之外的其他位置，以保持它们的新鲜和您的存储库的精简。

此外，从9.7.0开始，内置隐私插件被完全重写，现在与内置优化插件完美配合，这意味着外部资产可以通过与其余文档相同的优化管道进行处理。这意味着您可以在存储库之外存储和编辑未优化的文件，并让两个插件为您构建一个高度优化的网站。

如果您想实现单独的管道，即对某些图像进行不同的优化或排除某些图像的下载，您可以使用多个内置隐私插件的实例。

为什么Material for MkDocs设计上不能捆绑所有资产？

Material for MkDocs不能简单地捆绑所有自身资产的主要原因是与Google Fonts的集成，它提供了超过一千种不同的字体，可以用于呈现您的文档。大多数字体包括几种权重，并分为不同的字符集，以保持下载大小较小，因此浏览器只下载真正需要的内容。对于我们的默认常规字体Roboto，这导致总共42个*.woff2文件。

如果Material for MkDocs捆绑所有字体文件，下载大小将达到数百兆字节，从而减慢自动构建。此外，作者可能会添加外部资产，如第三方脚本或样式表，这些资产需要记住被定义为进一步的本地资产。

这正是内置隐私插件存在的原因——它自动化了手动下载所有外部资产的过程，以确保遵守GDPR，并具有一些技术限制。

展开以检查示例

对于官方文档，内置隐私插件下载以下资源：

.
└─ assets/external/
   ├─ unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
   ├─ fonts.googleapis.com/css
   └─ fonts.gstatic.com/s/
      ├─ roboto/v29/
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
      │  ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
      │  ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
      │  ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
      │  ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
      │  ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
      │  ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
      │  └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
      └─ robotomono/v13/
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
         ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
         ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtElOUlYIw.woff2
         ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEleUlYIw.woff2
         ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEluUlYIw.woff2
         ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEm-Ul.woff2
         ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEmOUlYIw.woff2
         └─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEn-UlYIw.woff2

自定义

自定义cookies

8.4.0
.zip

如果您自定义了cookie consent并添加了custom cookie，用户将被提示接受或拒绝您的自定义cookie。一旦用户接受或拒绝cookie同意，或更改设置，页面将重新加载1。使用附加JavaScript查询结果：

var consent = __md_get("__consent")
if (consent && consent.custom) {
  /* 用户接受了cookie */
} else {
  /* 用户拒绝了cookie */
}

extra_javascript:
  - javascripts/consent.js

  1. 我们重新加载页面以简化与自定义cookies的互操作性。如果Material for MkDocs实施基于回调的方法，作者需要确保正确更新所有使用cookies的脚本。此外，cookie同意仅在初始时回答，这就是为什么我们认为这是开发体验和用户体验的良好权衡。 ↩