MkDocs

MkDocs has an extra_javascript setting in mkdocs.yml that adds a script to every page with any theme. With Material for MkDocs you can instead extend the theme and write into <head>.

Copy your tracking snippet

In OnyxMetric, open your site's Site Settings and copy the tracking script. It looks like this:

<script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>

YOUR_SITE_ID is the numeric ID of your site.

Add the snippet to MkDocs

List the script URL under extra_javascript. MkDocs 1.5 and later accept the mapping form with async:

mkdocs.yml

extra_javascript:
  - path: https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID
    async: true

On MkDocs 1.4 or older, use the plain URL:

mkdocs.yml

extra_javascript:
  - https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID

Themes output these entries at the end of <body> rather than in <head>. The script still loads on every page.

Point Material at an overrides folder:

mkdocs.yml

theme:
  name: material
  custom_dir: overrides

Create overrides/main.html and fill the extrahead block, which Material reserves for custom tags in <head>:

overrides/main.html

{% extends "base.html" %}

{% block extrahead %}
  <script src="https://app.onyxmetric.com/api/script.js?siteId=YOUR_SITE_ID" async></script>
{% endblock %}

Rebuild with mkdocs build and deploy site/ (or run mkdocs gh-deploy). With Material's navigation.instant enabled, page changes go through the History API and are recorded as pageviews automatically.

Check that it works

Load your live site and click through a few pages. Pageviews show up in the OnyxMetric dashboard within seconds.

If nothing arrives:

View the page source and search for script.js?siteId= to confirm the tag is present.
In the browser's Network tab, check that script.js returns 200 and that requests go to /api/track.
Turn off ad blockers, or proxy the script through your own domain.
Read script troubleshooting for other causes.

Troubleshooting

Config error on async: the path mapping needs MkDocs 1.5 or newer. Check mkdocs --version, upgrade, or use the plain URL.
main.html ignored: it only works when theme.custom_dir is set and the file sits at overrides/main.html, relative to mkdocs.yml.
Previews are tracked: mkdocs serve renders the same config as a build. Use a separate OnyxMetric site for local work if that matters.

Next steps

Track custom events such as signups, purchases, and clicks.
Identify users to tie sessions to accounts.
Proxy the script through your own domain to get past ad blockers.
Script attributes let you skip or mask URLs and tag events.

Copy your tracking snippet

Add the snippet to MkDocs

Check that it works

Troubleshooting

Next steps

On this page