站点统计分析设置¶

与网络上提供的任何其他服务一样，了解您的项目文档的实际使用情况可能是成功的重要因素。Material-for-MkDocs 原生集成了 Google Analytics，并提供了可定制的 cookie 同意 功能和 反馈小部件。

配置¶

Google 分析¶

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，因此也需要提供 provider（供应商）和 property（属性）。但是，也可以提供自定义反馈集成。

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

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

* Metric name（指标名称）：页面是否有帮助
* Description（描述）：这个页面有帮助吗？
* Event parameter（事件参数）：data
* Unit of measurement（测量单位）：标准

* Dimensions（维度）：添加事件名称和页面位置
* Metrics（指标）：添加事件次数和页面是否有帮助（在步骤3中创建的自定义指标）
* Rows（行）：页面位置
* Values（值）：拖入事件次数和页面是否有帮助
* Filters（过滤器）：为事件名称添加一个新过滤器，`Event name / exactly matches / feedback`

每个评分具有以下属性：

此属性必须指向引用主题中包含的图标的有效图标路径，否则构建将不会成功。一些常见的组合包括：

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

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

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

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

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

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

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

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

GitHub Issues 的替代方案是Google Forms（谷歌表单）。

文章内使用¶

隐藏反馈小部件¶

可以通过在文档的前言（front matter）中添加 hide 属性来隐藏反馈小部件。在 Markdown 文件的顶部添加以下几行：

---
hide:
  - feedback
---

# Page title
...

自定义¶

自定义站点分析¶

要集成另一个提供基于JavaScript的跟踪解决方案的分析服务提供商，只需遵循主题扩展指南，并在 overrides 文件夹中创建一个新的局部文件。局部文件的名称用于通过 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

建议¶

国内无法使用 Google 分析，需要寻找一个类似的服务，或者自己开发