You want page views in Google Analytics or Plausible without maintaining a custom HTML shell or sprinkling <script> tags through MDX. docs.page loads tracking from docs.json on published pages only. Your local preview never sends events to production dashboards.
The scripts object in docs.json declares which analytics provider to use. docs.page injects the matching snippets when it renders a published page: production on the default branch, a vanity subdomain, or a custom domain.
Three providers are supported:
- Google Tag Manager: bootstrap a GTM container by container ID
- Google Analytics (GA4): load
gtag.jswith a measurement ID when Tag Manager is not configured - Plausible: load Plausible's hosted script or a self-hosted URL, scoped to your site domain
Configuration is declarative. You do not edit page templates or MDX to add tracking code.
During page render, docs.page reads scripts from the bundled configuration and outputs provider-specific <Script> tags in the HTML. For Google Tag Manager, it also inserts the standard <noscript> iframe fallback.
This runs on every published page view. The snippets are identical across routes. Page-level MDX does not control analytics.
When googleTagManager is set, docs.page injects the GTM bootstrap script only. It skips direct Google Analytics injection even if googleAnalytics is also present. Route GA (and other tags) through your GTM container instead.
Set googleAnalytics alone when you want a direct GA4 integration without Tag Manager.
Google Analytics reads page_title from the document <title> on each page_view event. docs.page sets that tag from each page's frontmatter title, then falls back to name in docs.json, then "Documentation". When a page omits frontmatter title, every route shares the same page_title in GA even though page_location / page_path still differ by URL.
A Markdown # heading in the page body does not set the document title. Only YAML frontmatter does.
Give every .md or .mdx file its own title in YAML frontmatter:
---
title: Your Page Title
---This applies whether GA loads directly from googleAnalytics or through a GA tag in Google Tag Manager. docs.page only injects the GTM bootstrap script; you configure the GA tag in your container.
See Page frontmatter and Write: Frontmatter.
Plausible requires a data-domain attribute that matches the hostname readers use. docs.page loads the Plausible script only when the request resolves to a configured custom domain or vanity subdomain. On the default docs.page/{owner}/{repo} path with no mapped domain, Plausible config has no effect.
Set plausible to true for Plausible's hosted script endpoint, or pass a string URL for self-hosted Plausible.
docs preview serves pages in preview request mode. In that mode, the script injector returns nothing: no GTM, GA, or Plausible tags are added to the document.
That keeps local editing and QA from inflating production analytics. Merge and push to your default branch (or open a hosted preview URL) to verify tags on a live-rendered page.