mkdocs-material/docs/setup/setting-up-site-analytics.md

template
overrides/main.html

Setting up site analytics

As with any other service offered on the web, understanding how your project documentation is actually used can be an essential success factor. While Material for MkDocs natively integrates with Google Analytics, other analytics providers can be used, too.

Configuration

Google Analytics

:octicons-file-code-24: Source · :octicons-milestone-24: Default: none

Material for MkDocs integrates with both, Google Analytics 4 and the now phasing out Universal Analytics (UA-*). Depending on the prefix of the property, add the following to mkdocs.yml:

=== "Google Analytics 4"

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

=== "Universal Analytics"

``` yaml
extra:
  analytics:
    provider: google
    property: UA-XXXXXXXX-X
```

Site search tracking

Besides basic page views, site search can also be tracked to understand better how people use your documentation and what they expect to find. To enable search tracking:

1. Go to your Google Analytics admin settings
2. Select the property for the respective tracking code
3. Go to the view settings tab.
4. Scroll down and enable site search settings
5. Set the query parameter to q.

Site search tracking is not supported with Google Analytics 4 due to the much more complicated manual setup. If you want to set up site search tracking yourself, this tutorial might be a good start.

Cookie consent

:octicons-file-code-24: Source · :octicons-beaker-24: Experimental · :octicons-heart-fill-24:{ .mdx-heart } Insiders only{ .mdx-insiders }

Material for MkDocs ships a native and extensible cookie consent form, which when enabled will ask the user for his consent prior to sending analytics. Add the following to mkdocs.yml:

extra:
  consent: true

When a user first visits your site, a cookie consent form is rendered:

Let's get this feature out of the experimental status! You are encouraged to share your feedback in #1914, so we can provide the necessary configuration options for easy customizations. If you wish to customize it today, you can override partials/consent.html.

Customization

Other analytics providers

:octicons-file-code-24: Source · :octicons-mortar-board-24: Difficulty: easy

In order to integrate another analytics service provider offering an asynchronous JavaScript-based tracking solution, you can extend the theme and override the analytics block:

{% block analytics %}
  <!-- Add custom analytics integration here -->
{% endblock %}

If you're using instant loading, you may use the location$ observable, which will emit the current URL to listen for navigation events and register a page view event with:

location$.subscribe(function(url) {
  /* Add custom page event tracking here */
})

Note that this must be integrated with additional JavaScript, and cannot be included as part of the analytics block, as it is included in the head of the document.