Summary
Add analytics tracking to the Docusaurus documentation site to measure page views and user engagement across all pages, including client-side (SPA) navigations.
Background
The docs site is built with Docusaurus v3, which is a Single Page Application (SPA). After the initial page load, navigating between pages uses client-side routing — the browser doesn't do a full page reload. This means analytics scripts injected via <head> only fire once on the first load. Subsequent page navigations are invisible unless the analytics solution explicitly listens for client-side route changes.
Implementation
1. Couchbase GTM (Google Tag Manager)
Add the Couchbase GTM script (GTM-MVPNN2) via Docusaurus headTags in docusaurus.config.js. This provides corporate-level tracking (ads, Marketo, etc.) consistent with other Couchbase documentation sites.
2. Docusaurus gtag Plugin (GA4)
Enable the built-in @docusaurus/plugin-google-gtag via the preset-classic configuration. This plugin hooks into Docusaurus's router and automatically sends a page_view event on every client-side navigation, solving the SPA tracking gap.
Why both? GTM alone doesn't track SPA navigations unless the GTM container has a History Change trigger configured. The gtag plugin reliably tracks every page view, including SPA navigations, while GTM handles Couchbase-wide corporate tracking.
Changes
website/docusaurus.config.js:
- Add
headTags with Couchbase GTM script
- Add
gtag configuration to preset-classic options
Verification
Reference
Summary
Add analytics tracking to the Docusaurus documentation site to measure page views and user engagement across all pages, including client-side (SPA) navigations.
Background
The docs site is built with Docusaurus v3, which is a Single Page Application (SPA). After the initial page load, navigating between pages uses client-side routing — the browser doesn't do a full page reload. This means analytics scripts injected via
<head>only fire once on the first load. Subsequent page navigations are invisible unless the analytics solution explicitly listens for client-side route changes.Implementation
1. Couchbase GTM (Google Tag Manager)
Add the Couchbase GTM script (
GTM-MVPNN2) via DocusaurusheadTagsindocusaurus.config.js. This provides corporate-level tracking (ads, Marketo, etc.) consistent with other Couchbase documentation sites.2. Docusaurus gtag Plugin (GA4)
Enable the built-in
@docusaurus/plugin-google-gtagvia thepreset-classicconfiguration. This plugin hooks into Docusaurus's router and automatically sends apage_viewevent on every client-side navigation, solving the SPA tracking gap.Why both? GTM alone doesn't track SPA navigations unless the GTM container has a History Change trigger configured. The gtag plugin reliably tracks every page view, including SPA navigations, while GTM handles Couchbase-wide corporate tracking.
Changes
website/docusaurus.config.js:headTagswith Couchbase GTM scriptgtagconfiguration topreset-classicoptionsVerification
metrics.couchbase.com/gtm.js?id=GTM-MVPNN2) loads on initial pagepage_viewon initial load with correct page URL/titlepage_viewon SPA navigation (client-side link clicks) with correct page URL/titleReference