MkDocs

MkDocs has an extra_javascript setting in mkdocs.yml that adds a script tag to every page, which works with any theme. If you run Material for MkDocs you can instead extend the theme and place the tag in <head> yourself.

Get your tracking snippet

In your Rybbit dashboard, open Site Settings → Tracking Script and copy your snippet. It looks like this:

<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

YOUR_SITE_ID is the numeric ID of your site. If you self-host Rybbit, app.rybbit.io is the domain of your own instance.

Add the snippet to MkDocs

Add the script URL to extra_javascript. MkDocs 1.5 and later accept the mapping form with a defer key:

mkdocs.yml

extra_javascript:
  - path: https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
    defer: true

On MkDocs 1.4 or older, list the plain URL instead:

mkdocs.yml

extra_javascript:
  - https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID

Themes render extra_javascript entries at the end of <body> rather than in <head>; the script still loads on every page.

Point Material at an overrides directory in mkdocs.yml:
mkdocs.yml
```
theme:
  name: material
  custom_dir: overrides
```

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

overrides/main.html

{% extends "base.html" %}

{% block extrahead %}
  <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
{% endblock %}

Rebuild with mkdocs build and deploy the site/ directory (or mkdocs gh-deploy).

If Material's navigation.instant feature is on, page changes go through the History API and Rybbit records them as pageviews without extra code.

Verify installation

Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

If nothing shows up:

View the page source and search for script.js?siteId= to confirm the snippet is on the page.
Open the browser Network tab and check that script.js returns 200 and that POST requests go to /api/track.
Disable ad blockers, or set up a proxy so the script loads from your own domain.
See the script troubleshooting guide for other common causes.

Troubleshooting

Config error on defer: the path / defer mapping needs MkDocs 1.5+. Run mkdocs --version and either upgrade or use the plain URL form.
main.html has no effect: the override only applies when theme.custom_dir is set and the file sits at overrides/main.html, relative to mkdocs.yml.
Local previews are tracked: mkdocs serve renders the same config as mkdocs build. Use a second Rybbit site for local work if that matters.

Next steps

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

Get your tracking snippet

Add the snippet to MkDocs

Verify installation

Troubleshooting

Next steps

On this page