# How to Configure Google Analytics and GTag in Docusaurus: Complete Setup Guide

> Learn how to configure Google Analytics and GTag in Docusaurus with our easy setup guide. Implement GA4 or Universal Analytics tracking for your Docusaurus site.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**Configure Google Analytics in Docusaurus by adding the `gtag` or `googleAnalytics` option to your `preset-classic` configuration in [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts), using a GA4 measurement ID (`G-XXXXXXXXXX`) for modern tracking or a UA ID for legacy Universal Analytics.**

Docusaurus ships with two first-party plugins that inject Google tracking scripts into your documentation site. According to the `facebook/docusaurus` source code, you enable these plugins directly through the classic preset options without installing additional dependencies.

## Understanding the Google Analytics Plugins

Docusaurus provides two official plugins for web analytics:

- **`@docusaurus/plugin-google-gtag`** – Inserts the modern **gtag.js** library for GA4 properties (measurement IDs starting with `G-`). This is the recommended approach for new projects.
- **`@docusaurus/plugin-google-analytics`** – Inserts the legacy **analytics.js** library for Universal Analytics properties (IDs starting with `UA-`). This plugin exists for backward compatibility only.

As defined in [`packages/docusaurus-preset-classic/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/src/options.ts), the preset accepts both `googleAnalytics?: GAPluginOptions` and `gtag?: GtagPluginOptions` fields. The preset implementation in [`packages/docusaurus-preset-classic/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/src/index.ts) (lines 81-92) transforms these options into concrete plugin configurations using the `makePluginConfig` utility.

## Configuration Architecture and Warnings

The canonical location for analytics configuration is the `presets` array in your site configuration file (typically [`website/docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.ts) in the repository structure). 

Defensive checks in the plugin source files prevent common migration errors. If you accidentally use the deprecated Docusaurus 1.x approach of setting `themeConfig.googleAnalytics` or `themeConfig.gtag`, the plugins emit console warnings:

- **Legacy analytics warning** – [`packages/docusaurus-plugin-google-analytics/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-google-analytics/src/index.ts) (lines 83-85)
- **GTag warning** – [`packages/docusaurus-plugin-google-gtag/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-google-gtag/src/index.ts) (lines 55-57)

These warnings remind you to move the configuration to the preset options level.

## Step-by-Step Configuration Guide

### Configure GTag for GA4 (Recommended)

For Google Analytics 4 properties, add the `gtag` object to your `classic` preset options. The `trackingID` parameter accepts either a single string or an array of strings for multiple properties.

```typescript
// docusaurus.config.ts
presets: [
  [
    'classic',
    {
      // ... other preset options ...
      gtag: {
        trackingID: ['G-E5CR2Q1NRE'],
      },
    },
  ],
],

```

The example above mirrors the configuration found in [`website/docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.ts) (lines 998-1002), where the Docusaurus team conditionally enables tracking only on production deploys.

### Configure Legacy Google Analytics

If you maintain a Universal Analytics property (UA-XXXX-X), use the `googleAnalytics` option instead:

```typescript
// docusaurus.config.ts
presets: [
  [
    'classic',
    {
      googleAnalytics: {
        trackingID: 'UA-12345678-1',
      },
    },
  ],
],

```

**Important:** Only configure one analytics method at a time. Providing both `gtag` and `googleAnalytics` simultaneously is not recommended and may cause duplicate tracking.

## Advanced Configuration Options

### Tracking Multiple Properties

The `gtag` plugin supports multiple measurement IDs by passing an array to `trackingID`. The plugin emits a separate `gtag('config', ...)` call for each ID during initialization.

```typescript
gtag: {
  trackingID: ['G-AAAAAA1', 'G-BBBBBB2'],
},

```

### IP Anonymization

For GDPR compliance or privacy requirements, enable IP anonymization by setting the `anonymizeIP` flag to `true`:

```typescript
gtag: {
  trackingID: ['G-XXXXXXXXXX'],
  anonymizeIP: true,
},

```

## Verifying Your Implementation

After configuration, verify the tracking script loads correctly:

1. Run a development or production build (`docusaurus build` or `docusaurus start`).
2. Open your browser's Developer Tools and navigate to the **Network** tab.
3. Filter for `gtag/js` (for GA4) or [`analytics.js`](https://github.com/facebook/docusaurus/blob/main/analytics.js) (for Universal Analytics).
4. Confirm the request returns a 200 status and contains your tracking ID.

The script injection happens during the server-side rendering phase. You can inspect the generated HTML source to verify the `<script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>` tag appears in the `<head>` section.

## Summary

- **Use `gtag`** in your `preset-classic` configuration for GA4 properties (IDs starting with `G-`).
- **Use `googleAnalytics`** only for legacy Universal Analytics properties (IDs starting with `UA-`).
- Configure options in [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts) within the presets array, not in `themeConfig`.
- Pass multiple tracking IDs as an array to the `trackingID` field for cross-property tracking.
- Enable `anonymizeIP: true` for enhanced privacy compliance.

## Frequently Asked Questions

### What is the difference between the Google Analytics and GTag plugins in Docusaurus?

The **Google Analytics plugin** (`@docusaurus/plugin-google-analytics`) loads the legacy [`analytics.js`](https://github.com/facebook/docusaurus/blob/main/analytics.js) library designed for Universal Analytics (UA) properties. The **GTag plugin** (`@docusaurus/plugin-google-gtag`) loads the modern [`gtag.js`](https://github.com/facebook/docusaurus/blob/main/gtag.js) library used by GA4 and Google Tag Manager. According to the Docusaurus source code, the GTag plugin is the preferred, actively maintained approach, while the analytics plugin exists solely for backward compatibility with existing UA properties.

### Can I use both Google Analytics and GTag simultaneously on the same site?

While the preset architecture technically allows both options to be defined simultaneously, you should **avoid running both plugins together** as this causes duplicate pageview tracking and inflated metrics. Choose the plugin that matches your Google Analytics property type: use `gtag` for GA4 measurement IDs (`G-XXXXXXXXXX`) and `googleAnalytics` only for legacy UA IDs (`UA-XXXXXXX-X`).

### How do I migrate from the old `themeConfig.googleAnalytics` setting?

If your configuration still uses the Docusaurus 1.x pattern of `themeConfig: { googleAnalytics: { trackingID: ... } }`, move the entire object to the `classic` preset options as shown in the configuration examples above. The plugins contain runtime checks in [`plugin-google-analytics/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/plugin-google-analytics/src/index.ts) and [`plugin-google-gtag/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/plugin-google-gtag/src/index.ts) that detect the deprecated `themeConfig` fields and emit console warnings directing you to the correct location.

### Where can I find my Google Analytics tracking ID?

For **GA4 properties**, your tracking ID (also called Measurement ID) follows the format `G-XXXXXXXXXX` and is found in your Google Analytics account under **Admin > Data Streams > [Your Website]**. For **Universal Analytics**, the tracking ID follows the format `UA-XXXXXXX-X` and is located under **Admin > Property > Property Settings**. Use the corresponding Docusaurus plugin based on which ID format you possess.