Analytics & Cookie Consent¶

Google Analytics¶

The theme supports both GA4 (recommended) and legacy Universal Analytics.

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX   # GA4 tag ID

For Universal Analytics:

extra:
  analytics:
    provider: google
    property: UA-XXXXXXXX-X

Analytics is only injected when site_url is set, so it will never fire during local development (mkdocs serve).

The script also checks for the browser's Do Not Track header and silently skips loading if it is set to 1.

Cookie consent banner (GDPR / LOPD)¶

To comply with the EU General Data Protection Regulation and the Spanish LOPD/LOPDGDD, enable the cookie consent banner:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX
    cookie_consent: true              # Show the banner
    privacy_policy: /privacy/        # Optional — link in the banner

When cookie_consent: true:

1. Analytics is not loaded on page load.
2. A banner appears at the bottom of the screen with Accept and Reject buttons.
3. If the user accepts, analytics is loaded immediately and the choice is saved in localStorage.
4. If the user rejects, no analytics scripts are loaded and any existing GA cookies are deleted.
5. A small cookie icon button stays in the bottom-right corner, allowing the user to reopen the banner and change their choice at any time.

Consent storage¶

The user's choice is stored in localStorage under the key mk-cookie-consent:

Privacy policy page¶

Create a docs/privacy.md file and reference it:

analytics:
  privacy_policy: /privacy/

Disabling analytics in development¶

Since analytics only fires when site_url is configured, you can keep site_url out of your mkdocs.yml during development, or use a separate config file:

# Production
mkdocs build --config-file mkdocs.yml

# Development (no analytics)
mkdocs serve --config-file mkdocs.dev.yml