From 085ba9ceb95684be6c24a06977510f00722a7458 Mon Sep 17 00:00:00 2001 From: Alex Duke Date: Fri, 3 Jul 2026 15:12:33 +0100 Subject: [PATCH 1/2] docs: clarify GA per-page tracking requires frontmatter title Co-authored-by: Cursor --- docs/customize/analytics.mdx | 5 +++++ docs/features/analytics.mdx | 18 ++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/customize/analytics.mdx b/docs/customize/analytics.mdx index ee966c47..4d454733 100644 --- a/docs/customize/analytics.mdx +++ b/docs/customize/analytics.mdx @@ -100,6 +100,10 @@ Open a **live** docs URL (not the local preview shell) and confirm the provider - Plausible: `script.js` from `plausible.io` or your self-hosted URL 3. **Confirm events in the provider dashboard:** GTM Preview or Tag Assistant for Tag Manager; GA4 **Realtime** for direct GA; Plausible dashboard for page views on your mapped domain. + + For Google Analytics, set `title` in frontmatter on every page. GA reads `page_title` from the document ``. Without a per-page title, every route shares your site `name` from `docs.json` (or `"Documentation"`) as the page title, even though URLs still differ. Body `#` headings do not set the document title. See [Per-page titles in Google Analytics](/features/analytics#per-page-titles-in-google-analytics). +</Warning> + <Info> On the default `docs.page/{owner}/{repo}` path with no custom domain, GTM and GA still load when configured. Plausible stays inactive until a domain is resolved. </Info> @@ -110,6 +114,7 @@ Open a **live** docs URL (not the local preview shell) and confirm the provider | --- | --- | --- | | No analytics scripts in local preview | Expected (preview mode suppresses `scripts`) | Verify on a published or branch-preview URL | | GA4 script missing but GTM is configured | GTM takes precedence over direct GA | Add GA as a tag inside GTM, or remove `googleTagManager` to use direct GA | +| GA shows one page title for every route | Pages missing frontmatter `title` | Add `title` to each page's YAML frontmatter (body `#` headings do not count); see [Page frontmatter](/reference/page-frontmatter) | | Plausible script never loads | No custom domain or vanity subdomain on the request | Use a [vanity subdomain](/features/vanity-subdomains) or [request a custom domain](/customize/custom-domain), then open the site on that hostname | | Plausible loads but no page views | `data-domain` must match the hostname readers use | Confirm the domain in Plausible matches your docs domain exactly | | Scripts present but no dashboard data | Provider misconfiguration or ad blockers | Check container or measurement ID spelling; test in a clean browser profile | diff --git a/docs/features/analytics.mdx b/docs/features/analytics.mdx index 325d09b5..18625f30 100644 --- a/docs/features/analytics.mdx +++ b/docs/features/analytics.mdx @@ -31,6 +31,24 @@ When `googleTagManager` is set, docs.page injects the GTM bootstrap script only. Set `googleAnalytics` alone when you want a direct GA4 integration without Tag Manager. +### Per-page titles in Google Analytics + +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: + +```yaml +--- +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](/reference/page-frontmatter) and [Write: Frontmatter](/authoring/write#frontmatter). + ### Plausible and site domains 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. From 3cd1d1aa0ab1a504d91dd11ef65da6c303c68b34 Mon Sep 17 00:00:00 2001 From: Alex Duke <alex.duke@invertase.io> Date: Fri, 3 Jul 2026 15:25:37 +0100 Subject: [PATCH 2/2] docs: use Info callout for GA frontmatter title note The per-page title guidance is behavioral context for accurate reports, not a caution about risky or irreversible actions. Co-authored-by: Cursor <cursoragent@cursor.com> --- docs/customize/analytics.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/customize/analytics.mdx b/docs/customize/analytics.mdx index 4d454733..081b0d48 100644 --- a/docs/customize/analytics.mdx +++ b/docs/customize/analytics.mdx @@ -100,9 +100,9 @@ Open a **live** docs URL (not the local preview shell) and confirm the provider - Plausible: `script.js` from `plausible.io` or your self-hosted URL 3. **Confirm events in the provider dashboard:** GTM Preview or Tag Assistant for Tag Manager; GA4 **Realtime** for direct GA; Plausible dashboard for page views on your mapped domain. -<Warning> +<Info> For Google Analytics, set `title` in frontmatter on every page. GA reads `page_title` from the document `<title>`. Without a per-page title, every route shares your site `name` from `docs.json` (or `"Documentation"`) as the page title, even though URLs still differ. Body `#` headings do not set the document title. See [Per-page titles in Google Analytics](/features/analytics#per-page-titles-in-google-analytics). -</Warning> +</Info> <Info> On the default `docs.page/{owner}/{repo}` path with no custom domain, GTM and GA still load when configured. Plausible stays inactive until a domain is resolved.