hugolib: Deprecate .Site.GoogleAnalytics

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

diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md
index d210765ab26aa3230e90c9159c17bdd49cd0dc7c..978412bb95191df56ee6ecfd69f027deb4bba644 100644 (file)
--- a/docs/content/en/getting-started/configuration.md
+++ b/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:
+
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
 
-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:
+{{< code-toggle file=hugo copy=false >}}
+[services.googleAnalytics]
+ID = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
 
-   ```googleAnalytics = "G-PPPPPPPP"```
+Now consider the following scenario:
 
-   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:
+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:
 
-   ```googleAnalytics = "G-SSSSSSSS"```
+    - `G-PPPPPPPPP` for production
+    - `G-SSSSSSSSS` for staging
 
-   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
+To satisfy these requirements, configure your site as follows:
 
-{{% note %}}
-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
 

diff --git a/docs/content/en/templates/internal.md b/docs/content/en/templates/internal.md
index 56315ec2c996b2d4f097431e9110c0f506203be0..52e846007b238b61b0b16bf3abfbd9d1a32db370 100644 (file)
--- a/docs/content/en/templates/internal.md
+++ b/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

diff --git a/docs/content/en/variables/site.md b/docs/content/en/variables/site.md
index ced5617b430e483c372d499ad2fd23b6596d1573..4605b9a429ce925329476757ffce16421120c0fe 100644 (file)
--- a/docs/content/en/variables/site.md
+++ b/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/)
 

diff --git a/hugolib/site_new.go b/hugolib/site_new.go
index 4db5eeb2871fb29bfbea2129007c07d3dbf149b8..d582b1b7922d1ee9f3935d37acd6bb7afa71f990 100644 (file)
--- a/hugolib/site_new.go
+++ b/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
 }
 

diff --git a/resources/page/site.go b/resources/page/site.go
index 7b8960fdd3dc692787fee07abdd8926c9e7e099e..527bc504675195ba29b97ec184c42656ece2b3b3 100644 (file)
--- a/resources/page/site.go
+++ b/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 ""
 }

diff --git a/tpl/tplimpl/embedded/templates/google_analytics.html b/tpl/tplimpl/embedded/templates/google_analytics.html
index f518b150c1ad6802365290a8756cf96376fc109c..ad88ae924907b0964b8e8a58118bc3605632c8a7 100644 (file)
--- a/tpl/tplimpl/embedded/templates/google_analytics.html
+++ b/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 -}}
\ No newline at end of file
+{{- end -}}

diff --git a/tpl/tplimpl/embedded/templates/google_analytics_async.html b/tpl/tplimpl/embedded/templates/google_analytics_async.html
index b7bf36faa9d4977b2e0cdcf5145cb810107482c7..c9ba8a2b3f55130f0b8594504aa51885508197cb 100644 (file)
--- a/tpl/tplimpl/embedded/templates/google_analytics_async.html
+++ b/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) {