feat(plugin-google-tag-manager): add new google-tag-manager plugin + deprecate google-analytics plugin (#8470)

Co-authored-by: Goolsby, Lane <lanegoolsby@rocketmortgage.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
fix https://github.com/facebook/docusaurus/issues/7221

website/docs/api/plugins/plugin-google-analytics.md

@@ -9,6 +9,16 @@ import APITable from '@site/src/components/APITable';
 
 The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead.
 
+:::danger Deprecated
+
+This plugin is **deprecated**, and will become useless on July 1, 2023.
+
+Google is [moving away from Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/).
+
+If you are still using this plugin with a `UA-*` tracking id, you should create a Google Analytics 4 account as soon as possible, and use [`@docusaurus/plugin-google-gtag`](./plugin-google-gtag.md) instead of this plugin. More details [here](https://github.com/facebook/docusaurus/issues/7221).
+
+:::
+
 :::caution production only
 
 This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.

website/docs/api/plugins/plugin-google-tag-manager.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 8
+slug: /api/plugins/@docusaurus/plugin-google-tag-manager
+---
+
+# 📦 plugin-google-tag-manager
+
+import APITable from '@site/src/components/APITable';
+
+A plugin for adding [Google Tag Manager (gtm.js)](https://developers.google.com/tag-platform/tag-manager) to a Docusaurus site. Use this plugin in conjunction with the standard [gtag plugin](./plugin-google-gtag.md) for in-depth analysis of how users are using your site.
+
+:::tip
+
+You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if tag manager is set up correctly!
+
+:::
+
+:::caution production only
+
+This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.
+
+:::
+
+## Installation {#installation}
+
+```bash npm2yarn
+npm install --save @docusaurus/plugin-google-tag-manager
+```
+
+:::tip
+
+If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
+
+You can configure this plugin through the preset options.
+
+:::
+
+## Configuration {#configuration}
+
+Accepted fields:
+
+```mdx-code-block
+<APITable>
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `containerId` | `string` | **Required** | Your Tag Manager container Id (usually starts with `GTM-`). |
+
+```mdx-code-block
+</APITable>
+```
+
+### Example configuration {#ex-config}
+
+You can configure this plugin through preset options or plugin options.
+
+:::tip
+
+Most Docusaurus users configure this plugin through the preset options.
+
+:::
+
+```js config-tabs
+// Preset Options: googleTagManager
+// Plugin Options: @docusaurus/plugin-google-tag-manager
+
+const config = {
+  containerId: 'GTM-12345',
+};
+```

website/docs/using-plugins.md

@@ -144,8 +144,9 @@ The classic preset is shipped by default to new Docusaurus websites created with
 - [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md)
 - [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md)
 - [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md)
-- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md)
 - [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md)
+- [`@docusaurus/plugin-google-tag-manager`](./api/plugins/plugin-google-tag-manager.md)
+- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) (**deprecated**)
 - [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md)
 
 The classic preset will relay each option entry to the respective plugin/theme.
@@ -172,7 +173,9 @@ module.exports = {
         sitemap: {},
         // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
         gtag: {},
-        // Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
+        // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
+        googleTagManager: {},
+        // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
         googleAnalytics: {},
       },
     ],