Google Analytics documenation #2101

TheJaredWilcurt · 2020-05-11T17:50:21Z

I'm trying to switch from Docsify, where, at runtime I would have this JS run:

let googleAnalyticsId = 'UA-1234567-50'; // default to dev
if (window.location.host.includes('apps-test.example.com')) {
  googleAnalyticsId = 'UA-1234567-59';
} else if (window.location.host.includes('apps.example.com')) {
  googleAnalyticsId = 'UA-1234567-51';
}
window.$docsify = {
  ga: googleAnalyticsId,
};

The documentation is vague and does not explain what the code is, or how it works:

google_analytics: ['UA-36723568-3', 'mkdocs.org']

https://www.mkdocs.org/user-guide/configuration/#google_analytics

Is the second argument a name? Something to match against before analytics are enabled? How would you go about defining which ID to use based on the current environment (dev/test/prod/local)? Can you hook into this on page load (since GA is just running in JS anyway) so the above logic can stay in the JavaScript?

Can the docs be updated to have these answers?

It looks like there is some theme or template file for analytics, but there is no example.

For others looking for a work around to the lack of proper documentation, here's the best thing I could come up with:

In the root of your project create a theme folder
Put footer.html in the folder
Edit it and add this:

<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

let googleAnalyticsId = 'UA-1234567-50'; // default to dev
if (window.location.host.includes('apps-test.example.com')) {
  googleAnalyticsId = 'UA-1234567-59';
} else if (window.location.host.includes('apps.example.com')) {
  googleAnalyticsId = 'UA-1234567-51';
}

ga('create', googleAnalyticsId, 'auto');
ga('send', 'pageview');
</script>

The text was updated successfully, but these errors were encountered:

waylan · 2020-05-11T21:59:41Z

In the mkdocs theme, those config options are used in the template here:

mkdocs/mkdocs/themes/mkdocs/base.html

Lines 44 to 56 in a4eb4eb

    
           {%- block analytics %} 
        
             {%- if config.google_analytics %} 
        
             <script> 
        
                 (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ 
        
                 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), 
        
                 m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) 
        
                 })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); 
        
                 ga('create', '{{ config.google_analytics[0] }}', '{{ config.google_analytics[1] }}'); 
        
                 ga('send', 'pageview'); 
        
             </script> 
        
             {%- endif %} 
        
           {%- endblock %}

And for the readthedocs theme:

mkdocs/mkdocs/themes/readthedocs/base.html

Lines 55 to 76 in a4eb4eb

    
             {%- block analytics %} 
        
             {% if config.google_analytics %} 
        
             <script> 
        
                 (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ 
        
                 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), 
        
                 m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) 
        
                 })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); 
        
                 ga('create', '{{ config.google_analytics[0] }}', '{{ config.google_analytics[1] }}'); 
        
                 ga('send', 'pageview'); 
        
             </script> 
        
             {% endif %} 
        
             {%- endblock %} 
        
           </head> 
        
           <body class="wy-body-for-nav" role="document"> 
        
             <div class="wy-grid-for-nav"> 
        
               {# SIDE NAV, TOGGLES ON MOBILE #} 
        
               <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav"> 
        
               <div class="wy-side-scroll">

Of course, for third-party themes, things may be different.

Regarding the two values, they are the two values passed to ga(create...). Of course, back when the documentation was written, it corresponded with Google documentation and was clear. Google has since changed their documentation which makes ours less clear.

In any event, a PR with suggested changes is always welcome.

sorenwacker · 2021-09-24T01:32:51Z

The documentation says something like:

extra:
  analytics:
    provider: google
    propertyl: UA-...

Which one is correct now??

tomchristie · 2024-04-12T06:37:50Z

Let's close this off in favor of #3630

Including GA should be supported as a template override, not a config option.

Any docs here should probably be generic - we can leave it to analytics providers to deal with their own "here's how to include us on your website" docs.

waylan added the Documentation label May 11, 2020

tomchristie mentioned this issue Apr 10, 2024

Remove Google Analytics from being hardcoded into the theme. #3630

Open

tomchristie closed this as not planned Won't fix, can't repro, duplicate, stale Apr 12, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Google Analytics documenation #2101

Google Analytics documenation #2101

TheJaredWilcurt commented May 11, 2020 •

edited

waylan commented May 11, 2020

sorenwacker commented Sep 24, 2021

tomchristie commented Apr 12, 2024 •

edited

Google Analytics documenation #2101

Google Analytics documenation #2101

Comments

TheJaredWilcurt commented May 11, 2020 • edited

waylan commented May 11, 2020

sorenwacker commented Sep 24, 2021

tomchristie commented Apr 12, 2024 • edited

TheJaredWilcurt commented May 11, 2020 •

edited

tomchristie commented Apr 12, 2024 •

edited