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:
+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:
-- 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
 
-This is how you need to configure your `hugo.toml` files considering the above scenario:
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
-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:
 
-   ```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
+Now consider the following scenario:
-3. Similarly in `staging/hugo.toml` you just need to have one line:
 
-   ```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 %}}
+To satisfy these requirements, configure your site as follows:
-Default environments are __development__ with `hugo server` and __production__ with `hugo`.
+
-{{%/ note %}}
+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) {