设置站点分析¶

与网络上提供的任何其他服务一样，了解您的项目 文档的实际使用可能是成功的关键因素。材料用于 MkDocs与Google Analytics原生集成，并提供可定制的 cookie consent和feedback widget。

配置¶

谷歌分析¶

Material for MkDocs与Google Analytics 4原生集成¹。如果你 已设置Google Analytics并拥有属性，请通过添加 将以下行转换为mkdocs.yml：

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

这个页面有用吗？¶

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

extra:
  analytics: # (1)!
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: >- # (2)!
            Thanks for your feedback! Help us improve this page by
            using our <a href="..." target="_blank" rel="noopener">feedback form</a>.

1. 此功能与Google Analytics原生集成， 这就是为什么“提供者”和“财产”也是必需的。然而，它也是 可以提供[自定义反馈集成]。

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

“title”和“ratings”这两个属性都是必需的。请注意，这是允许的 定义两个以上的评级，例如实现1-5星评级。自从 反馈小部件将数据发送到第三方服务，当然，它是原生的 与[cookie同意]功能集成²。

以下属性适用于每种评级：

此属性必须指向引用[任何捆绑的图标]的有效图标路径 使用[自定义图标]主题，否则构建将无法成功。一些流行 组合：

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

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

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

此属性的值在用户选择评级后显示。 它可能包含任意HTML标签，这对于询问 用户可以通过表单为当前页面提供更详细的反馈。 也可以用当前页面的URL和标题预先填写表单 使用以下占位符创建页面：

• {url} – Page URL
• {title} – Page title

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

在这个例子中，当点击链接时，用户会被重定向到“新 您的存储库的“issue”表单，带有预先填写的标题，包括路径 当前文档，例如：

[Feedback] Setting up site analytics – /setup/setting-up-site-analytics/

GitHub问题的替代方案是Google Forms。

使用¶

隐藏反馈小部件¶

[反馈小部件]可以隐藏在带有“hide”字样的文档中` 财产。在Markdown文件的顶部添加以下行：

---
hide:
  - feedback
---

# Page title
...

自定义¶

自定义站点分析¶

为了整合另一家提供 基于JavaScript的跟踪解决方案，只需按照[主题扩展]的指南进行操作 并在“override”文件夹中创建一个新的分部。该部分的名称为 用于通过mkdocs.yml配置自定义集成：

<script>
  /* Add custom analytics integration here, e.g. */
  var property = "{{ config.extra.analytics.property }}" // (1)!

  /* Wait for page to load and application to mount */
  document.addEventListener("DOMContentLoaded", function() {
    location$.subscribe(function(url) {
      /* Add custom page event tracking here */ // (2)!
    })
  })
</script>

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

自定义网站反馈¶

自定义反馈小部件集成只需要处理以下事件 由用户在某些帮助下与反馈小部件交互生成 [附加JavaScript]：

var feedback = document.forms.feedback
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