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

Configure Google Analytics in Docusaurus by adding the gtag or googleAnalytics option to your preset-classic configuration in 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, the preset accepts both googleAnalytics?: GAPluginOptions and gtag?: GtagPluginOptions fields. The preset implementation in 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 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 (lines 83-85)
• GTag warning – 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.

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

The example above mirrors the configuration found in 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:

// 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.

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

IP Anonymization

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

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 (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 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 library designed for Universal Analytics (UA) properties. The GTag plugin (@docusaurus/plugin-google-gtag) loads the modern 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}