Skip to content

πŸ“ˆ Open source, privacy-first web analytics β€” a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

MkDocs integration

Blue Mousee6827c5e473a
diff --git a/docs/docs/integration-guides.md b/docs/docs/integration-guides.md
index 9ba6e32ad..7a2bcbed0 100644
--- a/docs/docs/integration-guides.md
+++ b/docs/docs/integration-guides.md
@@ -41,6 +41,7 @@ Swetrix integrates with a wide range of platforms, frameworks, and tools. Choose
- [htmx](/htmx-integration)
- [Hugo](/hugo-integration)
- [Jekyll](/jekyll-integration)
+- [MkDocs / Material for MkDocs](/mkdocs-integration)
- [Next.js](/nextjs-integration)
- [Nuxt](/nuxt-integration)
- [Preact](/preact-integration)
diff --git a/docs/docs/integrations/mkdocs.md b/docs/docs/integrations/mkdocs.md
new file mode 100644
index 000000000..b481cd59d
--- /dev/null
+++ b/docs/docs/integrations/mkdocs.md
@@ -0,0 +1,229 @@
+---
+title: MkDocs / Material for MkDocs
+slug: /mkdocs-integration
+---
+
+Integrate Swetrix with your [MkDocs](https://www.mkdocs.org/) 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](https://squidfundez.github.io/mkdocs-material/) 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](https://squidfundez.github.io/mkdocs-material/customization/#extending-the-theme) mechanism.
+
+#### 1. Enable the overrides directory
+
+In your `mkdocs.yml`, add a `custom_dir` under the `theme` key:
+
+```yaml
+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:
+
+```html
+{% 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](https://swetrix.com/projects), otherwise tracking won't work.
+:::
+
+#### 3. Build and deploy
+
+```bash
+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
+
+```yaml
+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:
+
+```html
+{% 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`:**
+
+```yaml
+extra:
+ swetrix:
+ project_id: "YOUR_PROJECT_ID"
+```
+
+**2. Update the override template:**
+
+```html
+{% 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](https://www.mkdocs.org/user-guide/configuration/#hooks). 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:
+
+```html
+{% 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](/swetrix-js-reference#trackerrors) 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:
+
+```html
+<button onclick="swetrix.track({ ev: 'FEEDBACK_CLICK' })">
+ Send feedback
+</button>
+```
+
+### Example: tracking outbound links
+
+```html
+<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 only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)
+- Be fewer than 64 characters
+- Start with an English letter
+
+## 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](/swetrix-js-reference) β€” full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.
+- [MkDocs documentation](https://www.mkdocs.org/) β€” official MkDocs user guide.
+- [Material for MkDocs](https://squidfundez.github.io/mkdocs-material/) β€” documentation for the Material theme.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index bcc6f077b..9eac14b76 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -29,6 +29,7 @@ module.exports = {
'integrations/jekyll',
'integrations/joomla',
'integrations/laravel',
+ 'integrations/mkdocs',
'integrations/prestashop',
{
type: 'category',