diff --git a/userguide/config.toml b/userguide/config.toml index 2bfe49cc3..c4421bc91 100644 --- a/userguide/config.toml +++ b/userguide/config.toml @@ -44,8 +44,7 @@ anchor = "smart" [services] [services.googleAnalytics] -# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback]. -id = "UA-00000000-0" +id = "UA-00000000-0" # FIXME: https://github.com/google/docsy/issues/1097 # Language configuration @@ -131,10 +130,8 @@ sidebar_search_disable = false # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar navbar_logo = true -# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. -# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. -# If you want this feature, but occasionally need to remove the "Feedback" section from a single page, -# add "hide_feedback: true" to the page's front matter. +# For details concerning the page feedback widget, see +# https://www.docsy.dev/docs/adding-content/feedback/#user-feedback [params.ui.feedback] enable = true # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). diff --git a/userguide/content/en/docs/adding-content/feedback.md b/userguide/content/en/docs/adding-content/feedback.md index 70350c40c..55f043926 100644 --- a/userguide/content/en/docs/adding-content/feedback.md +++ b/userguide/content/en/docs/adding-content/feedback.md @@ -1,5 +1,5 @@ --- -title: Analytics, User Feedback, SEO +title: Analytics, User Feedback, and SEO date: 2019-06-05 description: >- Add Google Analytics tracking to your site, collect user feedback and learn @@ -9,63 +9,53 @@ weight: 8 ## Adding Analytics -The Docsy theme contains built-in support for -[Google Analytics](https://analytics.google.com/analytics/web/) via Hugo's -[internal template](https://gohugo.io/templates/internal/#google-analytics), -which is included in the theme. Once you set Analytics up as described below, -usage information for your site (such as page views) is sent to your Google -Analytics account. +The Docsy theme builds upon [Hugo's support for Google Analytics][hugo-ga], +which Hugo provides through [internal templates][]. Once you set up analytics as +described below, usage information for your site (such as page views) is sent to +your [Google Analytics][] account. -### Setup +### Prerequisites -1. Ensure you have - [set up a Google Analytics property](https://support.google.com/analytics/answer/1042508) - for your site: this gives you an Analytics ID to add to your config, which - Docsy in turn adds to all your site's pages. -2. Open `config.toml`/`config.yaml`/`config.json`. -3. Enable Google Analytics by setting the Tracking ID property to your site's - Analytics ID. +You will need an **analytics ID** for your website before proceeding +(technically it's called a measurement ID or property ID but we'll use the term +"analytics ID" in this guide). If you don't have one, see the **How to get +started** section of [Introducing Google Analytics 4 (GA4)][ga4-intro]. - {{< tabpane persistLang=false >}} +{{% alert title="Tip" %}} -{{< tab header="Configuration file:" disabled=true />}} + Your project's **analytics ID** is a string that starts with `G-` (a GA4 + measurement ID) or `UA-` (a universal analytics property ID). -{{< tab header="config.toml" lang="toml" >}} +{{% /alert %}} -[services.googleAnalytics] -id = "UA-00000000-0" +### Setup -{{< /tab >}} {{< tab header="config.yaml" lang="yaml" >}} +Enable Google Analytics by adding your project's analytics ID to the site +configuration file. For details, see [Configure Google Analytics][]. -services: - googleAnalytics: - id: UA-00000000-0 +{{% alert title="Warning" color="warning" %}} + -{{< /tab >}} {{< tab header="config.json" lang="json" >}} + You can configure your project's analytics ID by setting either the top-level + `googleAnalytics` config parameter or `services.googleAnalytics.id`. **Do not + define both,** otherwise this can result in [unexpected behavior][]. For + details, see [Is services.googleAnalytics.id an alias for + googleAnalytics][alias-discussion]. -{ - "services": { - "googleAnalytics": { - "id": "UA-00000000-0" - } - } -} + [alias-discussion]: https://discourse.gohugo.io/t/config-is-services-googleanalytics-id-an-alias-for-googleanalytics/39469 + [unexpected behavior]: https://github.com/google/docsy/issues/921 -{{< /tab >}} -{{< /tabpane >}} +{{% /alert %}} -4. Save and close `config.toml`/`config.yaml`/`config.json`. -5. Ensure that your site is built with `HUGO_ENV="production"`, as Docsy only - adds Analytics tracking to production-ready sites. You can specify this - variable as a command line flag to Hugo: +{{% alert title="Production-only feature!" color="primary" %}} + + Analytics are enabled _only_ for **production** builds (called "environments" + in Hugo terminology). For information about Hugo environments and how to set + them, see the following [discussion][]. - ```console - $ env HUGO_ENV="production" hugo - ``` + [discussion]: https://discourse.gohugo.io/t/what-does-setting-hugo-env-to-production-do/24669/2 - Alternatively, if you're using Netlify, you can specify it as a Netlify - [deployment setting](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables) - in `netlify.toml` or the Netlify UI, along with the Hugo version. +{{% /alert %}} ## User Feedback @@ -296,6 +286,11 @@ Add more meta tags as needed to your project's copy of the `head-end.html` partial. For details, see [Customizing templates]({{< ref "lookandfeel#customizing-templates" >}}). +[Configure Google Analytics]: https://gohugo.io/templates/internal/#configure-google-analytics +[ga4-intro]: https://support.google.com/analytics/answer/1042508 +[Google Analytics]: https://analytics.google.com/analytics/web/ +[hugo-ga]: https://gohugo.io/templates/internal/#google-analytics +[internal templates]: https://gohugo.io/templates/internal/ [layouts/partials/page-description.html]: https://github.com/google/docsy/blob/main/layouts/partials/page-description.html [site `params`]: https://gohugo.io/variables/site/#the-siteparams-variable [summary]: https://gohugo.io/content-management/summaries/