Support other analytics services

[nathanlesage]

Both built-in themes support a very easy Google Analytics implementation by providing two variables in your mkdocs.yml and this is really convenient and a great thing.

However, as Google Analytics does have its problems conforming to the new GDPR, and Matomo being a successful competitor in Europe, I would like to kindly request to add a matomo block to the base themes?

It's already possible with overwriting templates, but this way it would be even easier, as only two variables would need to be provided in mkdocs.yml. (See the Javascript boilerplate here: https://developer.matomo.org/guides/tracking-javascript-guide)

More or less this would be copying over the logic from the analytics template block, replace the ga-code with the matomo code, and we're done.

I would gladly do the PR if you like this idea!

[waylan]

As you note, this is already possible via overriding template blocks. Personally, I would be happy to leave that as the only way. However, I can also see the usability benefits of only needed to set a few config values. If this was to happen, then the existing solution should be ripped out and converted to a plugin with the relevant settings as config settings on the plugin itself. Then any other analytics services could have their own (third party) plugins as well with no need for any changes to MkDocs.

However, the existing Google Analytics was in place long before I joined the project and remains for backward compatibility reasons. Therefore we are stuck with it as the default. That being the case, for a transition period, if the existing root level settings are defined, config validation should issue a deprecation warning and activate the appropriate plugin with the settings passed in. At some future date, this special handling of the root level settings would be removed and an error would be raised if they are set.

Of course a PR is welcome.

[nathanlesage]

Thank you for the quick reply!

However, the existing Google Analytics was in place long before I joined the project and remains for backward compatibility reasons.

I see what you mean, and as you rightly state, it's no deal-breaker. However, the question would be: how long should backward compatibility go? I mean it's not bad to tell users to switch at some point. However, the idea using the plugin sounds great, as this would be a way to add a possibly unlimited amount of analytics softwares (maybe even using a specific file, something along the lines of the extra_css and extra_js options) and also make sure there's no hierarchy between them.

So I'll see to get into developing a plugin for that, and until then I'll go with the analytics-block :)

[waylan]

how long should backward compatibility go?

That's hard to say. I expect we would evaluate that after we have the existing Google Analytics solution broken out into a plugin.

[ChristianKniep]

@squidfunk Any chance you are going to review this again? I just got started with mkdocs and insiders and first time use of Google analytics is scary.

[squidfunk]

@ChristianKniep I'm afraid we cannot provide integrations for each and every analytics provider out there. However, the documentation states how to add a custom analytics provider, which can even be integrated with the cookie consent.

[fly3rman]

This is just my opinion but and i dont want to sound rude in any kind:
I would like to see opensource project support each other. Matomo is a REALLY good alternative to the google provider integration already provided as topic one on the Setting up site analytics documentation site.
+1 for "Custom site analytics" though!

[ayeks]

Because others may stumble over this issue, here my current very easy Matomo setup for mkdocs:

mkdocs.yml:

extra_javascript:
    - javascripts/matomo.js

The default matomo.js:

var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://matomo.YOURDOMAINHERE.com/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', 'XXXXXXX']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();

In addition to that you can just use the Matomo tracking image in the footer:

mkdocs.yml:

copyright: "Copyright &copy; 2023 ỲOUR COMPANY  <img referrerpolicy=\"no-referrer-when-downgrade\" src=\"https://matomo.YOURDOMAINHERE.com/matomo.php?idsite=XXXXXXX&amp;rec=1\" style=\"border:0\" alt=\"\" />"

[tomchristie]

Let's close this off in favor of #3630

@waylan assessed this correct back in 2019...

As you note, this is already possible via overriding template blocks. Personally, I would be happy to leave that as the only way.

Agree.

However, the existing Google Analytics was in place long before I joined the project ...

Yep, it was in there pretty much from the beginning.
It must have seemed sparkly and important to a young me at the time to have that as a simple config option.

I'm sure we can work through a graceful way to deprecate this.