refactor(ganalytics, gtag): move options out of themeConfig

[Josh-Cena]

Breaking changes

• For anyone who uses plugin-google-analytics or plugin-google-gtag: you would need to move your googleAnalytics or gtag options from themeConfig to preset-classic configuration.

// docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: /* ... */,
+       gtag: {
+         trackingID: 'xxx',
+       },
+       googleAnalytics: {
+         trackingID: 'xxx',
+       },
      },
    ],
  ],
  themeConfig: {
-   gtag: {
-     trackingID: 'xxx',
-   },
-   googleAnalytics: {
-     trackingID: 'xxx',
-   },
    // other options
  },
};

Why?

It has always been very counterintuitive to put the plugin options in theme configuration. It was made so previously due to technical limitations (separation of server data from client data), but now, with a better infrastructure, we can make the migration to make any future user less confused.

Motivation

Fulfill the long-standing todo of moving the options.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Build

[netlify]

✔️ [V2]

🔨 Explore the source changes: 9aadb5e

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/618ba37ec4da26000765255f

😎 Browse the preview: https://deploy-preview-5832--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	94
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5832--docusaurus-2.netlify.app/

[github-actions]

Size Change: +326 B (0%)

Total Size: 882 kB

Filename	Size	Change
website/.docusaurus/globalData.json	38.3 kB	+153 B (0%)
website/build/assets/js/main.********.js	475 kB	+174 B (0%)

ℹ️ View Unchanged

Filename	Size	Change
website/build/assets/css/styles.********.css	94.2 kB	0 B
website/build/blog/2017/12/14/introducing-docusaurus/index.html	66.1 kB	0 B
website/build/blog/index.html	36.8 kB	0 B
website/build/docs/index.html	44 kB	+1 B (0%)
website/build/docs/installation/index.html	51.5 kB	-2 B (0%)
website/build/index.html	29.5 kB	0 B
website/build/tests/docs/index.html	25.2 kB	0 B
website/build/tests/docs/standalone/index.html	21.7 kB	0 B

_{compressed-size-action}

[slorber]

LGTM, why still draft?

I suggest adding some edits in this doc page too: https://docusaurus.io/docs/presets#docusauruspreset-classic

[slorber]

not sure to understand what's the advantage of this syntax?

[Josh-Cena]

This is about how you're able to import it. Because we have esModuleInterop there's not a visible change. I forgot why I did this change but at least now it's "more correct". export = X is for module.exports = X and export default X is for module.exports.default = X.

[Josh-Cena]

LGTM, why still draft?

I actually don't know if my changes are correct because I don't know how to test them... Any ideas?

[slorber]

If you use the Docusaurus prod site locally it should send requests to GA when navigating, if requests are 200 then we can assume it's working

[Josh-Cena]

I'll take this as a success 👀

[slorber]

LGTM thanks 👍

[MateuszDabrowski]

I don't get the argument behind the change, but what is not counterintuitive is having gtag/ganalytics configuration in a completely different place from algolia configuration.

Also, if you believe that "counterintuitive to put the plugin options in theme configuration" - why not add it as a separate element of the plugins section? Moving it into a specific preset is just as (if not more) counterintuitive to me.

[Josh-Cena]

Algolia is a theme (theme-search-algolia); the google ones are plugins (plugin-google-analytics). It's quite intuitive for themes to have their configuration in the theme config, less so for plugins to have their options in the theme config as well. (In fact, we are considering the possibility of getting rid of the customCss option for theme-classic: #3678 after that, none of the themes would have any options. That seems to be the most natural API design.)

If you had previously been unaware of the nuance between themes and plugins and just put all of them under plugins, now is a good chance to try out the new shorthand configuration to actually make yourself aware of that.

As a regular helper on Discord, you can't imagine the confusion from newcomers. I've seen people declaring themeConfig multiple times because they just rigidly followed the instructions without even realizing there's already an entry called themeConfig. I've seen them putting themeConfig in the place where they are supposed to put plugin options. It just appears much more natural to co-locate plugins with their options.

why not add it as a separate element of the plugins section?

I have no idea what you meant. Preset options are directly passed down to individual plugins. When you write:

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        googleAnalytics: {
          trackingID: 'UA-141789564-1',
          anonymizeIP: true,
        },
      },
    ],
  ],
};

It's identical in every way to:

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-google-analytics',
      {
        trackingID: 'UA-141789564-1',
        anonymizeIP: true,
      },
    ],
  ],
};

You are welcome to use an individual plugin as opposed to the preset if the latter makes more sense to you.