Skip to content

Commit

Permalink
hugolib: Deprecate .Site.GoogleAnalytics
Browse files Browse the repository at this point in the history
Use .Site.Config.Services.GoogleAnalytics.ID instead.
  • Loading branch information
jmooring authored and bep committed Oct 17, 2023
1 parent d4016dd commit a692278
Show file tree
Hide file tree
Showing 7 changed files with 55 additions and 26 deletions.
64 changes: 46 additions & 18 deletions docs/content/en/getting-started/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}

Expand All @@ -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

Expand Down
3 changes: 2 additions & 1 deletion docs/content/en/templates/internal.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 0 additions & 3 deletions docs/content/en/variables/site.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/)

Expand Down
3 changes: 2 additions & 1 deletion hugolib/site_new.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand Down
2 changes: 2 additions & 0 deletions resources/page/site.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()
}
Expand Down Expand Up @@ -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 ""
}
Expand Down
4 changes: 2 additions & 2 deletions tpl/tplimpl/embedded/templates/google_analytics.html
Original file line number Diff line number Diff line change
@@ -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>
Expand Down Expand Up @@ -48,4 +48,4 @@
var dnt = (navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack);
var doNotTrack = (dnt == "1" || dnt == "yes");
{{- end -}}
{{- end -}}
{{- end -}}
2 changes: 1 addition & 1 deletion tpl/tplimpl/embedded/templates/google_analytics_async.html
Original file line number Diff line number Diff line change
@@ -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) {
Expand Down

0 comments on commit a692278

Please sign in to comment.