设置网站分析¶

与网络上提供的其他服务一样，了解您的项目文档实际如何使用可能是成功的关键因素。MkDocs的Material主题原生集成了Google Analytics，并提供可自定义的cookie同意和反馈小部件。

配置¶

Google Analytics¶

7.1.8

MkDocs的Material主题原生集成了Google Analytics 4¹。如果您已经设置了Google Analytics并拥有一个属性，请通过在mkdocs.yml中添加以下行来启用它：

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

这个页面有帮助吗？¶

8.4.0

可以在每个页面底部包含一个简单的反馈小部件，鼓励用户即时反馈页面是否有帮助。请在mkdocs.yml中添加以下行：

extra:
  analytics: # (1)!
    feedback:
      title: 这个页面有帮助吗？
      ratings:
        - icon: material/emoticon-happy-outline
          name: 这个页面很有帮助
          data: 1
          note: >-
            感谢您的反馈！
        - icon: material/emoticon-sad-outline
          name: 这个页面可以改进
          data: 0
          note: >- # (2)!
            感谢您的反馈！请通过我们的<a href="..." target="_blank" rel="noopener">反馈表单</a>帮助我们改进此页面。

1. 此功能原生集成了Google Analytics，因此provider和property也是必需的。然而，也可以提供自定义反馈集成。

2. 您可以在用户提交反馈后显示的备注中添加任意HTML标签，例如链接到反馈表单。

title和ratings两个属性都是必需的。请注意，允许定义超过两个评分，例如实现1-5星评分。由于反馈小部件将数据发送到第三方服务，因此它当然与cookie同意功能原生集成²。

以下属性适用于每个评分：

icon

此属性必须指向有效的图标路径，引用[主题中捆绑的任何图标][custom icons]，否则构建将失败。一些流行的组合：

• + – material/emoticon-happy-outline + material/emoticon-sad-outline
• + – material/thumb-up-outline + material/thumb-down-outline
• + – material/heart + material/heart-broken

name

此属性的值在用户交互时显示（即键盘聚焦或鼠标悬停），解释图标背后评分的含义。

data

此属性的值作为数据值与传输到Google Analytics³（或任何自定义集成）的自定义事件一起发送。

note

此属性的值在用户选择评分后显示。它可以包含任意HTML标签，这对于请求用户通过表单提供当前页面的更详细反馈特别有用。还可以通过使用以下占位符预填充表单的URL和标题：

• {url} – 页面URL
• {title} – 页面标题

https://github.com/.../issues/new/?title=[反馈]+{title}+-+{url}

在此示例中，当单击链接时，用户将被重定向到您存储库的“新问题”表单，标题预填充包括当前文档的路径，例如：

[反馈] 设置网站分析 – /setup/setting-up-site-analytics/

GitHub问题的替代方案是Google表单。

使用¶

隐藏反馈小部件¶

可以使用文档的前置信息hide属性隐藏反馈小部件。在Markdown文件顶部添加以下行：

---
hide:
  - feedback
---

# 页面标题
...

自定义¶

自定义网站分析¶

为了集成提供基于JavaScript的跟踪解决方案的其他分析服务提供商，只需按照主题扩展的指南操作，并在overrides文件夹中创建一个新的部分。部分的名称用于通过mkdocs.yml配置自定义集成：

<script>
  /* 在此添加自定义分析集成，例如 */
  var property = "{{ config.extra.analytics.property }}" // (1)!

  /* 等待页面加载和应用程序挂载 */
  document.addEventListener("DOMContentLoaded", function() {
    location$.subscribe(function(url) {
      /* 在此添加自定义页面事件跟踪 */ // (2)!
    })
  })
</script>

extra:
  analytics:
    provider: custom
    property: foobar # (1)!

自定义网站反馈¶

自定义反馈小部件集成只需处理用户与反馈小部件交互时生成的事件，借助一些额外的JavaScript：

document$.subscribe(function() {
  var feedback = document.forms.feedback
  if (typeof feedback === "undefined") return

  feedback.hidden = false // (1)!

  feedback.addEventListener("submit", function(ev) {
    ev.preventDefault()

    var page = document.location.pathname // (2)!
    var data = ev.submitter.getAttribute("data-md-value")

    console.log(page, data) // (3)!

    feedback.firstElementChild.disabled = true // (4)!

    var note = feedback.querySelector(
      ".md-feedback__note [data-md-value='" + data + "']"
    )
    if (note)
      note.hidden = false // (5)!
  })
})

extra_javascript:
  - javascripts/feedback.js