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¶

Source · 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¶

Other analytics providers¶

Source · 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:

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.