MkDocs / Material for MkDocs

Integrate Swetrix with your MkDocs site to track page views, monitor errors, and capture custom events — all while staying privacy-friendly and GDPR-compliant.

MkDocs is a Python-powered static site generator geared towards building project documentation. Material for MkDocs is the most popular MkDocs theme. Since MkDocs produces plain HTML pages, Swetrix tracks each page view automatically on every navigation.

Installation

The recommended approach is to override the base template and inject the Swetrix tracking script into every page.

Material for MkDocs

If you're using the Material theme (most common), use the theme extension mechanism.

1. Enable the overrides directory

In your mkdocs.yml, add a custom_dir under the theme key:

theme:
  name: material
  custom_dir: overrides

2. Create the override template

Create the file overrides/main.html in your project root with the following content:

{% extends "base.html" %}

{% block extrahead %}
  {{ super() }}
  <script src="https://swetrix.org/swetrix.js" defer></script>
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      swetrix.init('YOUR_PROJECT_ID')
      swetrix.trackViews()
    })
  </script>
{% endblock %}

{% block content %}
  {{ super() }}
  <noscript>
    <img
      src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"
      alt=""
      referrerpolicy="no-referrer-when-downgrade"
    />
  </noscript>
{% endblock %}

caution

Replace YOUR_PROJECT_ID with your actual Project ID from the Swetrix dashboard, otherwise tracking won't work.

3. Build and deploy

mkdocs build

The generated site/ directory will include the tracking script on every page.

Plain MkDocs (no Material theme)

If you're using a different MkDocs theme, you can use the same custom_dir approach. The exact block names depend on your theme.

1. Set a custom directory

theme:
  name: readthedocs
  custom_dir: overrides

2. Create a base template override

Create overrides/main.html (the file name depends on your theme's base template). For the default readthedocs theme:

{% extends "base.html" %}

{% block footer %}
  {{ super() }}
  <script src="https://swetrix.org/swetrix.js" defer></script>
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      swetrix.init('YOUR_PROJECT_ID')
      swetrix.trackViews()
    })
  </script>
  <noscript>
    <img
      src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"
      alt=""
      referrerpolicy="no-referrer-when-downgrade"
    />
  </noscript>
{% endblock %}

tip

Check your theme's documentation for the available template blocks. Most themes expose a footer, scripts, or extra block you can extend.

Using config variables (optional)

Store your Project ID in mkdocs.yml to keep it out of the template and make it easy to manage across environments.

1. Add to mkdocs.yml:

extra:
  swetrix:
    project_id: "YOUR_PROJECT_ID"

2. Update the override template:

{% extends "base.html" %}

{% block extrahead %}
  {{ super() }}
  {% if config.extra.swetrix and config.extra.swetrix.project_id %}
  <script src="https://swetrix.org/swetrix.js" defer></script>
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      swetrix.init('{{ config.extra.swetrix.project_id }}')
      swetrix.trackViews()
    })
  </script>
  {% endif %}
{% endblock %}

{% block content %}
  {{ super() }}
  {% if config.extra.swetrix and config.extra.swetrix.project_id %}
  <noscript>
    <img
      src="https://api.swetrix.com/log/noscript?pid={{ config.extra.swetrix.project_id }}"
      alt=""
      referrerpolicy="no-referrer-when-downgrade"
    />
  </noscript>
  {% endif %}
{% endblock %}

Disable tracking in development

By default, Swetrix ignores traffic from localhost, so page views during mkdocs serve won't be sent to your dashboard. No extra configuration is needed.

If you want to avoid loading the script entirely during development, you can use an environment variable via a MkDocs hook. However, since localhost traffic is already ignored, this is typically unnecessary.

tip

Since Swetrix ignores localhost traffic by default, your development page views won't appear in the dashboard even without any special configuration.

Error tracking

Enable automatic client-side error monitoring by adding trackErrors() alongside your existing initialisation:

{% extends "base.html" %}

{% block extrahead %}
  {{ super() }}
  <script src="https://swetrix.org/swetrix.js" defer></script>
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      swetrix.init('YOUR_PROJECT_ID')
      swetrix.trackViews()
      swetrix.trackErrors()
    })
  </script>
{% endblock %}

Errors will appear in the Errors tab of your project dashboard. See the tracking script reference for options like sampleRate and callback.

Tracking custom events

Custom events let you track specific user interactions — button clicks, form submissions, downloads, and more.

Inline event tracking

You can add event tracking to any element on a Markdown page using raw HTML:

<button onclick="swetrix.track({ ev: 'FEEDBACK_CLICK' })">
  Send feedback
</button>

Example: tracking outbound links

<a
  href="https://github.com/your-org/your-project"
  onclick="swetrix.track({ ev: 'GITHUB_CLICK', meta: { source: 'docs' } })"
>
  View on GitHub
</a>

Event naming rules

Event names must:

• Contain any characters (including spaces, unicode, etc.)
• Be no longer than 256 characters

Check your installation

After adding the tracking script, build your site with mkdocs build and deploy it. Visit your live documentation site and navigate through a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.

Further reading

• Tracking script reference — full API documentation for init(), track(), trackViews(), trackErrors(), and more.
• MkDocs documentation — official MkDocs user guide.
• Material for MkDocs — documentation for the Material theme.