hugolib: Deprecate .Site.GoogleAnalytics

Use .Site.Config.Services.GoogleAnalytics.ID instead.

docs/content/en/getting-started/configuration.md

@@ -44,12 +44,12 @@ In addition to using a single site configuration file, one can use the `configDi
 - Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc...
 - Each file's content must be top-level, for example:
 
-{{< code-toggle file="hugo" >}}
+{{< code-toggle file="hugo" copy=false >}}
 [Params]
   foo = "bar"
 {{< /code-toggle >}}
 
-{{< code-toggle file="params" >}}
+{{< code-toggle file="params" copy=false >}}
 foo = "bar"
 {{< /code-toggle >}}
 
@@ -74,28 +74,56 @@ foo = "bar"
 
 Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
 
-Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify `googleAnalytics = "G-XXXXXXXX"` in `hugo.toml`. Now consider the following scenario:
-- You don't want the Analytics code to be loaded in development i.e. in your `localhost`
-- You want to use separate googleAnalytics IDs for your production & staging environments (say):
-  - `G-PPPPPPPP` for production
-  - `G-SSSSSSSS` for staging
+Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
 
-This is how you need to configure your `hugo.toml` files considering the above scenario:
-1. In `_default/hugo.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo server`. This works since, by default Hugo sets `Environment=development` when you run `hugo server` which uses the configuration files from `_default` folder
-2. In `production/hugo.toml` you just need to have one line:
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
 
-   ```googleAnalytics = "G-PPPPPPPP"```
+{{< code-toggle file=hugo copy=false >}}
+[services.googleAnalytics]
+ID = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
 
-   You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this configuration file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/hugo.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website
-3. Similarly in `staging/hugo.toml` you just need to have one line:
+Now consider the following scenario:
 
-   ```googleAnalytics = "G-SSSSSSSS"```
+1. You don't want to load the analytics code when running `hugo server`.
+2. You want to use different Google tag IDs for your production and staging environments. For example:
 
-   Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website
+    - `G-PPPPPPPPP` for production
+    - `G-SSSSSSSSS` for staging
 
-{{% note %}}
-Default environments are __development__ with `hugo server` and __production__ with `hugo`.
-{{%/ note %}}
+To satisfy these requirements, configure your site as follows:
+
+1. `config/_default/hugo.toml`
+
+    Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
+
+    By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
+
+2. `config/production/hugo.toml`
+
+    Include this section only:
+
+    {{< code-toggle file=hugo copy=false >}}
+    [services.googleAnalytics]
+    ID = 'G-PPPPPPPPP'
+    {{< /code-toggle >}}
+
+    You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
+
+    By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
+
+3. `config/staging/hugo.toml`
+
+    Include this section only:
+
+    {{< code-toggle file=hugo copy=false >}}
+    [services.googleAnalytics]
+    ID = 'G-SSSSSSSSS'
+    {{< /code-toggle >}}
+
+    You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
+
+    To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
 
 ## Merge configuration from themes
 

docs/content/en/templates/internal.md

@@ -32,7 +32,8 @@ Provide your tracking ID in your configuration file:
 
 **Google Analytics 4 (gtag.js)**
 {{< code-toggle file="hugo" >}}
-googleAnalytics = "G-MEASUREMENT_ID"
+[services.googleAnalytics]
+ID = "G-MEASUREMENT_ID"
 {{</ code-toggle >}}
 
 ### Use the Google Analytics template

docs/content/en/variables/site.md

@@ -38,9 +38,6 @@ All the methods below, e.g. `.Site.RegularPages` can also be reached via the glo
 .Site.DisqusShortname
 : a string representing the shortname of the Disqus shortcode as defined in the site configuration.
 
-.Site.GoogleAnalytics
-: a string representing your tracking code for Google Analytics as defined in the site configuration.
-
 .Site.Home
 : reference to the homepage's [page object](/variables/page/)
 

hugolib/site_new.go

@@ -452,8 +452,9 @@ func (s *Site) DisqusShortname() string {
 	return s.Config().Services.Disqus.Shortname
 }
 
-// TODO(bep): deprecate.
+// Deprecated: Use .Site.Config.Services.GoogleAnalytics.ID instead
 func (s *Site) GoogleAnalytics() string {
+	helpers.Deprecated(".Site.GoogleAnalytics", "Use .Site.Config.Services.GoogleAnalytics.ID instead.", false)
 	return s.Config().Services.GoogleAnalytics.ID
 }
 

resources/page/site.go

@@ -176,6 +176,7 @@ func (s *siteWrapper) Authors() AuthorList {
 	return AuthorList{}
 }
 
+// Deprecated: Use .Site.Config.Services.GoogleAnalytics.ID instead
 func (s *siteWrapper) GoogleAnalytics() string {
 	return s.s.GoogleAnalytics()
 }
@@ -373,6 +374,7 @@ func (t testSite) Languages() langs.Languages {
 	return nil
 }
 
+// Deprecated: Use .Site.Config.Services.GoogleAnalytics.ID instead
 func (t testSite) GoogleAnalytics() string {
 	return ""
 }

tpl/tplimpl/embedded/templates/google_analytics.html

@@ -1,5 +1,5 @@
 {{- $pc := .Site.Config.Privacy.GoogleAnalytics -}}
-{{- if not $pc.Disable }}{{ with .Site.GoogleAnalytics -}}
+{{- if not $pc.Disable }}{{ with .Site.Config.Services.GoogleAnalytics.ID -}}
 {{ if hasPrefix . "G-"}}
 <script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
 <script>
@@ -48,4 +48,4 @@ var doNotTrack = false;
 var dnt = (navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack);
 var doNotTrack = (dnt == "1" || dnt == "yes");
 {{- end -}}
-{{- end -}}
+{{- end -}}

tpl/tplimpl/embedded/templates/google_analytics_async.html

@@ -1,7 +1,7 @@
 {{ warnf "_internal/google_analytics_async.html is no longer supported by Google and will be removed in a future version of Hugo" }}
 {{- $pc := .Site.Config.Privacy.GoogleAnalytics -}}
 {{- if not $pc.Disable -}}
-{{ with .Site.GoogleAnalytics }}
+{{ with .Site.Config.Services.GoogleAnalytics.ID }}
 <script type="application/javascript">
 {{ template "__ga_js_set_doNotTrack" $ }}
 if (!doNotTrack) {