From d109e91c51e1b490b3c2278e31525fb38d385ad7 Mon Sep 17 00:00:00 2001 From: Josh-Cena Date: Sat, 30 Oct 2021 12:19:11 +0800 Subject: [PATCH 1/6] refactor(ganalytics, gtag): move options out of themeConfig --- .../package.json | 3 +- .../src/index.ts | 49 +++++++++-------- .../src/plugin-google-analytics.d.ts | 12 ++--- .../package.json | 3 +- .../docusaurus-plugin-google-gtag/src/gtag.ts | 10 ++-- .../src/index.ts | 53 +++++++++++-------- .../src/plugin-google-gtag.d.ts | 12 ++--- .../docusaurus-preset-classic/src/index.ts | 11 ++-- .../src/preset-classic.d.ts | 8 ++- website/docusaurus.config.js | 10 ++-- 10 files changed, 92 insertions(+), 79 deletions(-) diff --git a/packages/docusaurus-plugin-google-analytics/package.json b/packages/docusaurus-plugin-google-analytics/package.json index 2d4df876ee7e..5be6bb96f74a 100644 --- a/packages/docusaurus-plugin-google-analytics/package.json +++ b/packages/docusaurus-plugin-google-analytics/package.json @@ -18,7 +18,8 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.9" + "@docusaurus/core": "2.0.0-beta.9", + "@docusaurus/utils-validation": "2.0.0-beta.9" }, "devDependencies": { "@docusaurus/types": "2.0.0-beta.9" diff --git a/packages/docusaurus-plugin-google-analytics/src/index.ts b/packages/docusaurus-plugin-google-analytics/src/index.ts index 083a1ff7f42a..0f699c5c9072 100644 --- a/packages/docusaurus-plugin-google-analytics/src/index.ts +++ b/packages/docusaurus-plugin-google-analytics/src/index.ts @@ -6,30 +6,21 @@ */ import path from 'path'; -import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types'; -import type {ThemeConfig} from '@docusaurus/plugin-google-analytics'; - -export default function pluginGoogleAnalytics(context: LoadContext): Plugin { - const { - siteConfig: {themeConfig}, - } = context; - const {googleAnalytics} = themeConfig as ThemeConfig; - - if (!googleAnalytics) { - throw new Error( - `You need to specify "googleAnalytics" object in "themeConfig" with "trackingId" field in it to use docusaurus-plugin-google-analytics.`, - ); - } - - const {trackingID, anonymizeIP} = googleAnalytics; - - if (!trackingID) { - throw new Error( - 'You specified the "googleAnalytics" object in "themeConfig" but the "trackingID" field was missing. ' + - 'Please ensure this is not a mistake.', - ); - } +import {Joi} from '@docusaurus/utils-validation'; +import type { + LoadContext, + Plugin, + HtmlTags, + OptionValidationContext, + ValidationResult, +} from '@docusaurus/types'; +import type {PluginOptions} from '@docusaurus/plugin-google-analytics'; +export default function pluginGoogleAnalytics( + context: LoadContext, + options: PluginOptions, +): Plugin { + const {trackingID, anonymizeIP} = options; const isProd = process.env.NODE_ENV === 'production'; return { @@ -74,3 +65,15 @@ export default function pluginGoogleAnalytics(context: LoadContext): Plugin { }, }; } + +const pluginOptionsSchema = Joi.object({ + trackingID: Joi.string().required(), + anonymizeIP: Joi.boolean().default(false), +}); + +export function validateOptions({ + validate, + options, +}: OptionValidationContext): ValidationResult { + return validate(pluginOptionsSchema, options); +} diff --git a/packages/docusaurus-plugin-google-analytics/src/plugin-google-analytics.d.ts b/packages/docusaurus-plugin-google-analytics/src/plugin-google-analytics.d.ts index fb0e0626f7c2..c23d43a7b424 100644 --- a/packages/docusaurus-plugin-google-analytics/src/plugin-google-analytics.d.ts +++ b/packages/docusaurus-plugin-google-analytics/src/plugin-google-analytics.d.ts @@ -5,9 +5,9 @@ * LICENSE file in the root directory of this source tree. */ -export interface ThemeConfig { - googleAnalytics?: { - trackingID: string; - anonymizeIP?: boolean; - }; -} +export type PluginOptions = { + trackingID: string; + anonymizeIP: boolean; +}; + +export type Options = Partial; diff --git a/packages/docusaurus-plugin-google-gtag/package.json b/packages/docusaurus-plugin-google-gtag/package.json index d95aa9a302e5..599cf606f0ff 100644 --- a/packages/docusaurus-plugin-google-gtag/package.json +++ b/packages/docusaurus-plugin-google-gtag/package.json @@ -18,7 +18,8 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.9" + "@docusaurus/core": "2.0.0-beta.9", + "@docusaurus/utils-validation": "2.0.0-beta.9" }, "devDependencies": { "@docusaurus/types": "2.0.0-beta.9" diff --git a/packages/docusaurus-plugin-google-gtag/src/gtag.ts b/packages/docusaurus-plugin-google-gtag/src/gtag.ts index c448b112d8fd..349ddfae0a60 100644 --- a/packages/docusaurus-plugin-google-gtag/src/gtag.ts +++ b/packages/docusaurus-plugin-google-gtag/src/gtag.ts @@ -6,17 +6,17 @@ */ import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; -import siteConfig from '@generated/docusaurus.config'; -import type {ThemeConfig} from '@docusaurus/plugin-google-gtag'; +import {usePluginData} from '@docusaurus/useGlobalData'; +import type {PluginOptions} from '@docusaurus/plugin-google-gtag'; export default (function () { if (!ExecutionEnvironment.canUseDOM) { return null; } - const {themeConfig} = siteConfig; - const {gtag} = themeConfig as ThemeConfig; - const {trackingID} = gtag!; + const {trackingID} = usePluginData( + 'docusaurus-plugin-google-gtag', + ); return { onRouteUpdate({location}: {location: Location}) { diff --git a/packages/docusaurus-plugin-google-gtag/src/index.ts b/packages/docusaurus-plugin-google-gtag/src/index.ts index 09a4d467e591..438cdd8c9433 100644 --- a/packages/docusaurus-plugin-google-gtag/src/index.ts +++ b/packages/docusaurus-plugin-google-gtag/src/index.ts @@ -6,35 +6,30 @@ */ import path from 'path'; -import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types'; -import type {ThemeConfig} from '@docusaurus/plugin-google-gtag'; - -export default function pluginGoogleGtag(context: LoadContext): Plugin { - const { - siteConfig: {themeConfig}, - } = context; - const {gtag} = themeConfig as ThemeConfig; - - if (!gtag) { - throw new Error( - `You need to specify "gtag" object in "themeConfig" with "trackingId" field in it to use docusaurus-plugin-google-gtag.`, - ); - } - - const {anonymizeIP, trackingID} = gtag; - - if (!trackingID) { - throw new Error( - 'You specified the "gtag" object in "themeConfig" but the "trackingID" field was missing. ' + - 'Please ensure this is not a mistake.', - ); - } +import {Joi} from '@docusaurus/utils-validation'; +import type { + LoadContext, + Plugin, + HtmlTags, + OptionValidationContext, + ValidationResult, +} from '@docusaurus/types'; +import type {PluginOptions} from '@docusaurus/plugin-google-gtag'; +export default function pluginGoogleGtag( + context: LoadContext, + options: PluginOptions, +): Plugin { + const {anonymizeIP, trackingID} = options; const isProd = process.env.NODE_ENV === 'production'; return { name: 'docusaurus-plugin-google-gtag', + async contentLoaded({actions}) { + actions.setGlobalData(options); + }, + getClientModules() { return isProd ? [path.resolve(__dirname, './gtag')] : []; }, @@ -83,3 +78,15 @@ export default function pluginGoogleGtag(context: LoadContext): Plugin { }, }; } + +const pluginOptionsSchema = Joi.object({ + trackingID: Joi.string().required(), + anonymizeIP: Joi.boolean().default(false), +}); + +export function validateOptions({ + validate, + options, +}: OptionValidationContext): ValidationResult { + return validate(pluginOptionsSchema, options); +} diff --git a/packages/docusaurus-plugin-google-gtag/src/plugin-google-gtag.d.ts b/packages/docusaurus-plugin-google-gtag/src/plugin-google-gtag.d.ts index 18d997bd814e..c23d43a7b424 100644 --- a/packages/docusaurus-plugin-google-gtag/src/plugin-google-gtag.d.ts +++ b/packages/docusaurus-plugin-google-gtag/src/plugin-google-gtag.d.ts @@ -5,9 +5,9 @@ * LICENSE file in the root directory of this source tree. */ -export interface ThemeConfig { - gtag?: { - trackingID: string; - anonymizeIP?: boolean; - }; -} +export type PluginOptions = { + trackingID: string; + anonymizeIP: boolean; +}; + +export type Options = Partial; diff --git a/packages/docusaurus-preset-classic/src/index.ts b/packages/docusaurus-preset-classic/src/index.ts index 0b9976015533..220bcbbbe69d 100644 --- a/packages/docusaurus-preset-classic/src/index.ts +++ b/packages/docusaurus-preset-classic/src/index.ts @@ -29,9 +29,10 @@ export default function preset( ): Preset { const {siteConfig} = context; const {themeConfig} = siteConfig; - const {algolia, googleAnalytics, gtag} = themeConfig as Partial; + const {algolia} = themeConfig as Partial; const isProd = process.env.NODE_ENV === 'production'; - const {debug, docs, blog, pages, sitemap, theme, ...rest} = opts; + const {debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag, ...rest} = + opts; const themes: PluginConfig[] = []; themes.push(makePluginConfig('@docusaurus/theme-classic', theme)); @@ -50,13 +51,15 @@ export default function preset( plugins.push(makePluginConfig('@docusaurus/plugin-content-pages', pages)); } if (isProd && googleAnalytics) { - plugins.push(require.resolve('@docusaurus/plugin-google-analytics')); + plugins.push( + makePluginConfig('@docusaurus/plugin-google-analytics', googleAnalytics) + ); } if (debug || (debug === undefined && !isProd)) { plugins.push(require.resolve('@docusaurus/plugin-debug')); } if (isProd && gtag) { - plugins.push(require.resolve('@docusaurus/plugin-google-gtag')); + plugins.push(makePluginConfig('@docusaurus/plugin-google-gtag', gtag)); } if (isProd && sitemap !== false) { plugins.push(makePluginConfig('@docusaurus/plugin-sitemap', sitemap)); diff --git a/packages/docusaurus-preset-classic/src/preset-classic.d.ts b/packages/docusaurus-preset-classic/src/preset-classic.d.ts index a007881dd552..6a21ed2d8cc3 100644 --- a/packages/docusaurus-preset-classic/src/preset-classic.d.ts +++ b/packages/docusaurus-preset-classic/src/preset-classic.d.ts @@ -12,13 +12,11 @@ export type Options = { pages?: false | import('@docusaurus/plugin-content-pages').Options; sitemap?: false | import('@docusaurus/plugin-sitemap').Options; theme?: import('@docusaurus/theme-classic').Options; + analytics?: import('@docusaurus/plugin-google-analytics').Options; + gtag?: import('@docusaurus/plugin-google-gtag').Options; }; export type ThemeConfig = import('@docusaurus/types').ThemeConfig & - import('@docusaurus/theme-common').UserThemeConfig & - // Those plugins themeConfigs should rather be moved to preset/plugin options - // Plugin data can be made available to browser thank to the globalData api - import('@docusaurus/plugin-google-analytics').ThemeConfig & - import('@docusaurus/plugin-google-gtag').ThemeConfig & { + import('@docusaurus/theme-common').UserThemeConfig & { algolia?: unknown; // TODO type plugin }; diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 033433424b07..421c430f6401 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -301,6 +301,11 @@ const config = { theme: { customCss: [require.resolve('./src/css/custom.css')], }, + gtag: !isDeployPreview + ? { + trackingID: 'UA-141789564-1', + } + : undefined, }), ], ], @@ -328,11 +333,6 @@ const config = { }, image: 'img/docusaurus-soc.png', // metadatas: [{name: 'twitter:card', content: 'summary'}], - gtag: !isDeployPreview - ? { - trackingID: 'UA-141789564-1', - } - : undefined, algolia: { appId: 'X1Z85QJPUV', apiKey: 'bf7211c161e8205da2f933a02534105a', From 32ed9daa259a2367e2f97b8e1fb95c359b687a25 Mon Sep 17 00:00:00 2001 From: Josh-Cena Date: Sat, 30 Oct 2021 12:35:34 +0800 Subject: [PATCH 2/6] Forbid themeConfig options --- .../src/index.ts | 13 +++++++++++++ .../docusaurus-plugin-google-gtag/src/index.ts | 13 +++++++++++++ packages/docusaurus-preset-classic/src/index.ts | 15 ++++++++++++--- .../src/preset-classic.d.ts | 2 +- 4 files changed, 39 insertions(+), 4 deletions(-) diff --git a/packages/docusaurus-plugin-google-analytics/src/index.ts b/packages/docusaurus-plugin-google-analytics/src/index.ts index 0f699c5c9072..b3c302b339ba 100644 --- a/packages/docusaurus-plugin-google-analytics/src/index.ts +++ b/packages/docusaurus-plugin-google-analytics/src/index.ts @@ -13,6 +13,8 @@ import type { HtmlTags, OptionValidationContext, ValidationResult, + ThemeConfig, + ThemeConfigValidationContext, } from '@docusaurus/types'; import type {PluginOptions} from '@docusaurus/plugin-google-analytics'; @@ -77,3 +79,14 @@ export function validateOptions({ }: OptionValidationContext): ValidationResult { return validate(pluginOptionsSchema, options); } + +export function validateThemeConfig({ + themeConfig, +}: ThemeConfigValidationContext): ValidationResult { + if (themeConfig.googleAnalytics) { + throw new Error( + 'The "googleAnalytics" field in themeConfig should now be specified as option for plugin-google-analytics. More information at .', + ); + } + return themeConfig; +} diff --git a/packages/docusaurus-plugin-google-gtag/src/index.ts b/packages/docusaurus-plugin-google-gtag/src/index.ts index 438cdd8c9433..30bf6980e559 100644 --- a/packages/docusaurus-plugin-google-gtag/src/index.ts +++ b/packages/docusaurus-plugin-google-gtag/src/index.ts @@ -13,6 +13,8 @@ import type { HtmlTags, OptionValidationContext, ValidationResult, + ThemeConfig, + ThemeConfigValidationContext, } from '@docusaurus/types'; import type {PluginOptions} from '@docusaurus/plugin-google-gtag'; @@ -90,3 +92,14 @@ export function validateOptions({ }: OptionValidationContext): ValidationResult { return validate(pluginOptionsSchema, options); } + +export function validateThemeConfig({ + themeConfig, +}: ThemeConfigValidationContext): ValidationResult { + if (themeConfig.gtag) { + throw new Error( + 'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. More information at .', + ); + } + return themeConfig; +} diff --git a/packages/docusaurus-preset-classic/src/index.ts b/packages/docusaurus-preset-classic/src/index.ts index 220bcbbbe69d..c953734167af 100644 --- a/packages/docusaurus-preset-classic/src/index.ts +++ b/packages/docusaurus-preset-classic/src/index.ts @@ -31,8 +31,17 @@ export default function preset( const {themeConfig} = siteConfig; const {algolia} = themeConfig as Partial; const isProd = process.env.NODE_ENV === 'production'; - const {debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag, ...rest} = - opts; + const { + debug, + docs, + blog, + pages, + sitemap, + theme, + googleAnalytics, + gtag, + ...rest + } = opts; const themes: PluginConfig[] = []; themes.push(makePluginConfig('@docusaurus/theme-classic', theme)); @@ -52,7 +61,7 @@ export default function preset( } if (isProd && googleAnalytics) { plugins.push( - makePluginConfig('@docusaurus/plugin-google-analytics', googleAnalytics) + makePluginConfig('@docusaurus/plugin-google-analytics', googleAnalytics), ); } if (debug || (debug === undefined && !isProd)) { diff --git a/packages/docusaurus-preset-classic/src/preset-classic.d.ts b/packages/docusaurus-preset-classic/src/preset-classic.d.ts index 6a21ed2d8cc3..84d71226fa83 100644 --- a/packages/docusaurus-preset-classic/src/preset-classic.d.ts +++ b/packages/docusaurus-preset-classic/src/preset-classic.d.ts @@ -12,7 +12,7 @@ export type Options = { pages?: false | import('@docusaurus/plugin-content-pages').Options; sitemap?: false | import('@docusaurus/plugin-sitemap').Options; theme?: import('@docusaurus/theme-classic').Options; - analytics?: import('@docusaurus/plugin-google-analytics').Options; + googleAnalytics?: import('@docusaurus/plugin-google-analytics').Options; gtag?: import('@docusaurus/plugin-google-gtag').Options; }; From 92a36c69f848db03b24a4290d2208d7a850645da Mon Sep 17 00:00:00 2001 From: Josh-Cena Date: Sat, 30 Oct 2021 12:39:48 +0800 Subject: [PATCH 3/6] Add PR link --- packages/docusaurus-plugin-google-analytics/src/index.ts | 2 +- packages/docusaurus-plugin-google-gtag/src/index.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus-plugin-google-analytics/src/index.ts b/packages/docusaurus-plugin-google-analytics/src/index.ts index b3c302b339ba..94000117f3ed 100644 --- a/packages/docusaurus-plugin-google-analytics/src/index.ts +++ b/packages/docusaurus-plugin-google-analytics/src/index.ts @@ -85,7 +85,7 @@ export function validateThemeConfig({ }: ThemeConfigValidationContext): ValidationResult { if (themeConfig.googleAnalytics) { throw new Error( - 'The "googleAnalytics" field in themeConfig should now be specified as option for plugin-google-analytics. More information at .', + 'The "googleAnalytics" field in themeConfig should now be specified as option for plugin-google-analytics. More information at https://github.com/facebook/docusaurus/pull/5832.', ); } return themeConfig; diff --git a/packages/docusaurus-plugin-google-gtag/src/index.ts b/packages/docusaurus-plugin-google-gtag/src/index.ts index 30bf6980e559..f1bc87a7cd66 100644 --- a/packages/docusaurus-plugin-google-gtag/src/index.ts +++ b/packages/docusaurus-plugin-google-gtag/src/index.ts @@ -98,7 +98,7 @@ export function validateThemeConfig({ }: ThemeConfigValidationContext): ValidationResult { if (themeConfig.gtag) { throw new Error( - 'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. More information at .', + 'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. More information at https://github.com/facebook/docusaurus/pull/5832.', ); } return themeConfig; From a0a9d7478f423b566d1261ae996c7c7df2f52a36 Mon Sep 17 00:00:00 2001 From: Josh-Cena Date: Sat, 30 Oct 2021 12:44:07 +0800 Subject: [PATCH 4/6] Add key names to error message --- packages/docusaurus-preset-classic/src/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docusaurus-preset-classic/src/index.ts b/packages/docusaurus-preset-classic/src/index.ts index c953734167af..310a4104a3df 100644 --- a/packages/docusaurus-preset-classic/src/index.ts +++ b/packages/docusaurus-preset-classic/src/index.ts @@ -77,7 +77,7 @@ export default function preset( throw new Error( `Unrecognized keys ${Object.keys(rest).join( ', ', - )} found in preset-classic configuration. The allowed keys are debug, docs, blog, pages, sitemap, theme. Check the documentation: https://docusaurus.io/docs/presets#docusauruspreset-classic for more information on how to configure individual plugins.`, + )} found in preset-classic configuration. The allowed keys are debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag. Check the documentation: https://docusaurus.io/docs/presets#docusauruspreset-classic for more information on how to configure individual plugins.`, ); } From 99da7a603534d6ccbd0653c44c60d8b24ad1739c Mon Sep 17 00:00:00 2001 From: Josh-Cena Date: Sat, 30 Oct 2021 13:26:39 +0800 Subject: [PATCH 5/6] Fix? --- packages/docusaurus-module-type-aliases/src/index.d.ts | 10 +++++----- packages/docusaurus-plugin-google-gtag/src/gtag.ts | 7 +++---- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/packages/docusaurus-module-type-aliases/src/index.d.ts b/packages/docusaurus-module-type-aliases/src/index.d.ts index a905e91ff892..bae8e4fa389d 100644 --- a/packages/docusaurus-module-type-aliases/src/index.d.ts +++ b/packages/docusaurus-module-type-aliases/src/index.d.ts @@ -22,7 +22,7 @@ declare module '@generated/site-metadata' { import type {DocusaurusSiteMetadata} from '@docusaurus/types'; const siteMetadata: DocusaurusSiteMetadata; - export default siteMetadata; + export = siteMetadata; } declare module '@generated/registry' { @@ -48,13 +48,13 @@ declare module '@generated/routes' { declare module '@generated/routesChunkNames' { const routesChunkNames: Record>; - export default routesChunkNames; + export = routesChunkNames; } declare module '@generated/globalData' { // eslint-disable-next-line @typescript-eslint/no-explicit-any const globalData: Record; - export default globalData; + export = globalData; } declare module '@generated/i18n' { @@ -64,12 +64,12 @@ declare module '@generated/i18n' { currentLocale: string; localeConfigs: Record; }; - export default i18n; + export = i18n; } declare module '@generated/codeTranslations' { const codeTranslations: Record; - export default codeTranslations; + export = codeTranslations; } declare module '@theme-original/*'; diff --git a/packages/docusaurus-plugin-google-gtag/src/gtag.ts b/packages/docusaurus-plugin-google-gtag/src/gtag.ts index 349ddfae0a60..4e07afe4d8eb 100644 --- a/packages/docusaurus-plugin-google-gtag/src/gtag.ts +++ b/packages/docusaurus-plugin-google-gtag/src/gtag.ts @@ -6,7 +6,7 @@ */ import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; -import {usePluginData} from '@docusaurus/useGlobalData'; +import globalData from '@generated/globalData'; import type {PluginOptions} from '@docusaurus/plugin-google-gtag'; export default (function () { @@ -14,9 +14,8 @@ export default (function () { return null; } - const {trackingID} = usePluginData( - 'docusaurus-plugin-google-gtag', - ); + const {trackingID} = globalData['docusaurus-plugin-google-gtag'] + .default as PluginOptions; return { onRouteUpdate({location}: {location: Location}) { From f71458d6e96f720e8a30daf62c07096b027d73c0 Mon Sep 17 00:00:00 2001 From: Josh-Cena Date: Sun, 7 Nov 2021 12:20:23 +0800 Subject: [PATCH 6/6] Doc updates --- .../api/plugins/plugin-google-analytics.md | 75 ++++++++++++++++-- .../docs/api/plugins/plugin-google-gtag.md | 76 ++++++++++++++++--- website/docs/presets.md | 4 + 3 files changed, 138 insertions(+), 17 deletions(-) diff --git a/website/docs/api/plugins/plugin-google-analytics.md b/website/docs/api/plugins/plugin-google-analytics.md index 738c5f6e34d4..daaee18ab40a 100644 --- a/website/docs/api/plugins/plugin-google-analytics.md +++ b/website/docs/api/plugins/plugin-google-analytics.md @@ -20,15 +20,74 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it ## Configuration {#configuration} +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `trackingID` | `string` | **Required** | The tracking ID of your analytics service. | +| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. | + + + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + trackingID: 'UA-141789564-1', + anonymizeIP: true, +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + googleAnalytics: { + trackingID: 'UA-141789564-1', + anonymizeIP: true, + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + ```js title="docusaurus.config.js" module.exports = { - plugins: ['@docusaurus/plugin-google-analytics'], - themeConfig: { - googleAnalytics: { - trackingID: 'UA-141789564-1', - // Optional fields. - anonymizeIP: true, // Should IPs be anonymized? - }, - }, + plugins: [ + [ + '@docusaurus/plugin-google-analytics', + // highlight-start + { + trackingID: 'UA-141789564-1', + anonymizeIP: true, + }, + // highlight-end + ], + ], }; ``` diff --git a/website/docs/api/plugins/plugin-google-gtag.md b/website/docs/api/plugins/plugin-google-gtag.md index 53b760c36c40..3ab8992a5441 100644 --- a/website/docs/api/plugins/plugin-google-gtag.md +++ b/website/docs/api/plugins/plugin-google-gtag.md @@ -26,16 +26,74 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it ## Configuration {#configuration} +Accepted fields: + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `trackingID` | `string` | **Required** | The tracking ID of your gtag service. | +| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. | + + + +## Example configuration {#ex-config} + +Here's an example configuration object. + +You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). + +:::tip + +Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). + +::: + +```js +const config = { + trackingID: 'UA-141789564-1', + anonymizeIP: true, +}; +``` + +### Preset options {#ex-config-preset} + +If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + // highlight-start + gtag: { + trackingID: 'UA-141789564-1', + anonymizeIP: true, + }, + // highlight-end + }, + ], + ], +}; +``` + +### Plugin options {#ex-config-plugin} + +If you are using a standalone plugin, provide options directly to the plugin: + ```js title="docusaurus.config.js" module.exports = { - plugins: ['@docusaurus/plugin-google-gtag'], - themeConfig: { - gtag: { - // You can also use your "G-" Measurement ID here. - trackingID: 'UA-141789564-1', - // Optional fields. - anonymizeIP: true, // Should IPs be anonymized? - }, - }, + plugins: [ + [ + '@docusaurus/plugin-google-gtag', + // highlight-start + { + trackingID: 'UA-141789564-1', + anonymizeIP: true, + }, + // highlight-end + ], + ], }; ``` diff --git a/website/docs/presets.md b/website/docs/presets.md index bfde28292374..e359ca404b49 100644 --- a/website/docs/presets.md +++ b/website/docs/presets.md @@ -106,6 +106,10 @@ module.exports = { pages: {}, // Will be passed to @docusaurus/plugin-content-sitemap (false to disable) 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) + googleAnalytics: {}, }, ], ],