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 services can be used, too.

Configuration

Google Analytics

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

After heading over to your Google Analytics account to create a new property in order to obtain a unique tracking id of the form UA-XXXXXXXX-X, add it to mkdocs.yml:

google_analytics:
  - UA-XXXXXXXX-X
  - auto

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.

Customization

Using other analytics services

: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 %}

Using instant loading

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

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:

app.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.