π 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!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
MkDocs integration
Blue Mousee6827c5e473a
diff --git a/docs/docs/integration-guides.md b/docs/docs/integration-guides.mdindex 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.mdnew file mode 100644index 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.jsindex 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',