1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-11 15:26:05 +01:00
mkdocs-material/docs/setup/setting-up-site-analytics.md

82 lines
2.4 KiB
Markdown
Raw Normal View History

2020-07-22 09:54:17 +02:00
---
template: overrides/main.html
---
# Setting up site analytics
2020-07-26 14:46:09 +02:00
As with any other service offered on the web, understanding how your project
2020-07-22 09:54:17 +02:00
documentation is actually used can be an essential success factor. While
2020-07-22 11:57:41 +02:00
Material for MkDocs natively integrates with [Google Analytics][1], [other
analytics services][2] can be used, too.
2020-07-22 09:54:17 +02:00
[1]: https://developers.google.com/analytics
2020-09-03 15:32:32 +02:00
[2]: #other-analytics-providers
2020-07-22 09:54:17 +02:00
## Configuration
2020-07-22 11:57:41 +02:00
### Google Analytics
2020-07-22 09:54:17 +02:00
2020-07-22 11:57:41 +02:00
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
2020-07-22 09:54:17 +02:00
After heading over to your [Google Analytics][1] account to [create a new
2020-07-26 14:46:09 +02:00
property][4] in order to obtain a unique tracking id of the form
`UA-XXXXXXXX-X`, add it to `mkdocs.yml`:
2020-07-22 09:54:17 +02:00
``` yaml
google_analytics:
- UA-XXXXXXXX-X
- auto
```
2020-07-22 11:57:41 +02:00
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
[4]: https://support.google.com/analytics/answer/1042508
2020-07-22 09:54:17 +02:00
2020-07-24 14:30:03 +02:00
#### Site search tracking
2020-07-22 09:54:17 +02:00
2020-07-26 14:46:09 +02:00
Besides basic page views, _site search_ can also be tracked to understand better
2020-07-22 09:54:17 +02:00
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
2020-07-22 09:54:17 +02:00
[:octicons-file-code-24: Source][3] ·
2020-07-22 09:54:17 +02:00
:octicons-mortar-board-24: Difficulty: _easy_
In order to integrate another analytics service provider offering an
2020-07-22 11:57:41 +02:00
asynchronous JavaScript-based tracking solution, you can [extend the theme][5]
and [override the `analytics` block][6]:
``` html
2020-07-22 11:57:41 +02:00
{% block analytics %}
<!-- Add custom analytics integration here -->
2020-07-22 11:57:41 +02:00
{% endblock %}
```
2020-07-22 09:54:17 +02:00
2020-07-22 11:57:41 +02:00
[5]: ../customization.md#extending-the-theme
[6]: ../customization.md#overriding-blocks
2020-07-22 09:54:17 +02:00
2020-07-22 19:11:22 +02:00
If you're using [instant loading][7], you may use the `location$` observable,
2020-07-22 11:57:41 +02:00
which will emit the current `URL` to listen for navigation events and register
a page view event with:
2020-07-22 09:54:17 +02:00
``` js
2020-07-22 11:57:41 +02:00
app.location$.subscribe(function(url) {
/* Add custom page event tracking here */
2020-07-22 09:54:17 +02:00
})
```
2020-07-22 11:57:41 +02:00
Note that this must be integrated with [additional JavaScript][8], and cannot be
2020-07-26 14:46:09 +02:00
included as part of the `analytics` block, as it is included in the `head` of
2020-07-22 11:57:41 +02:00
the document.
[7]: setting-up-navigation.md#instant-loading
[8]: ../customization.md#additional-javascript