Analytics docs rework: factor out UA-to-GA4 instructions, and more (#312)

Author: chalin

.htmltest.yml

@@ -5,6 +5,7 @@ TestFilesConcurrently: true
 IgnoreDirs:
 IgnoreInternalURLs: # list of paths
 IgnoreURLs: # list of regexes of URLs or path to be ignored
+  - ^https?://localhost
   - \?no-link-check
   # FIXME: temporary ignore rules
   - assistance\.md

docs/analytics/README.md

@@ -0,0 +1,23 @@
+# Analytics
+
+## Google Analytics
+
+- [CNCF sandbox][] projects currently onboarding, should open a [Service Desk][]
+  ticket to either:
+  - Request a transfer of their existing GA properties to the **CNCF Projects**
+    Google Analytics account. The first step is to make [email protected] and
+    Administrator of their existing GA account.
+  - Request the creation of a new analytics property.
+- For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your
+  [Docsy][]-based website, see [Adding Analytics][].
+
+> **Archived instructions**: for details on how to migrate from Universal
+> Analytics to GA4, see
+> [Migrating Universal to Google Analytics 4](ua-to-ga4.md).
+
+[adding analytics]:
+  https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics
+[CNCF sandbox]: https://github.com/cncf/sandbox
+[docsy]: https://www.docsy.dev
+[ga4]: https://support.google.com/analytics/answer/10089681
+[service desk]: https://github.com/cncf/servicedesk

docs/analytics.md docs/analytics/ua-to-ga4.mddocs/analytics.md renamed to docs/analytics/ua-to-ga4.md

@@ -2,23 +2,13 @@
 cSpell:ignore: gtag kubernetes
 ---
 
-# Analytics
+# Migrating Universal to Google Analytics 4
 
-This page describes how to setup or upgrade Google Analytics (GA) for your CNCF
-project's website.
+This page describes how to migrate your CNCF project from Google's [Universal
+Analytics][ua] (UA) to [Google Analytics 4][ga4] (GA4).
 
-> **Deprecation notice**: Google's [Universal Analytics will be going away][ua]
-> in 2023.
-
-When adding analytics to a new CNCF project website, use [Google Analytics
-4][ga4] (GA4).
-
-## Adding Google Analytics
-
-For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your
-[Docsy][]-based website, see [Adding Analytics][].
-
-## Migrating to Google Analytics 4
+> **Deprecation notice**: Google started deprecating UA in 2023. As of 2024, UA
+> is no longer supported, and UA data is no longer accessible.
 
 There are many ways to upgrade your project to [GA4][]. We describe one such
 process below. Adapt it to your needs. Useful resources to consider include:
@@ -30,7 +20,7 @@ process below. Adapt it to your needs. Useful resources to consider include:
 - **Help center** resource: [Migrate from Universal Analytics to Google
   Analytics 4][migration-help]
 
-### Stage 0 - preparation
+## Stage 0 - preparation
 
 In preparation for the migration, follow these steps:
 
@@ -51,7 +41,7 @@ In preparation for the migration, follow these steps:
    - Take note of which library or libraries (some sites use both) your site is
      using.
 
-### Stage 1 - create a GA4 site tag
+## Stage 1 - create a GA4 site tag
 
 Objectives:
 
@@ -138,7 +128,7 @@ Follow these steps:
     -- provided that there are active users. You should see roughly the same
     number and distribution of active users reported by the UA console.
 
-### Stage 2 - configure the GA4 ID as the main analytics ID
+## Stage 2 - configure the GA4 ID as the main analytics ID
 
 GA4 only works when your project's website is configured using the [gtag.js][]
 analytics library.
@@ -174,7 +164,7 @@ analytics library.
       partial. In this case, make use of the GA4 measurement ID in your partial
       or site config file, as appropriate.
 
-### Stage 3 - switch to native support for GA
+## Stage 3 - switch to native support for GA
 
 In cases where your project website (temporarily) used some custom layouts or
 code (such as custom Hugo partials) to enable GA4, consider removing the custom

docusaurus.config.ts

@@ -7,14 +7,18 @@ import type * as Preset from '@docusaurus/preset-classic';
 const title = 'CNCF TechDocs';
 const repo = 'https://github.com/cncf/techdocs';
 
+const buildEnv = process.env.BUILD_ENV || 'production';
+const isProd = buildEnv === 'production';
+
 const config: Config = {
   title,
   // tagline: '',
   favicon:
     'https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico', // TODO: localize?
 
-  // Production URL:
-  url: 'https://cncf-techdocs.netlify.app/', // FIXME if/once we get a domain
+  url: isProd
+    ? 'https://cncf-techdocs.netlify.app'
+    : process.env.DEPLOY_PRIME_URL || 'http://localhost:3000',
   baseUrl: '/',
 
   // GitHub pages deployment config. TODO: this still useful?
@@ -37,7 +41,7 @@ const config: Config = {
       {
         docs: {
           sidebarPath: './sidebars.ts',
-          editUrl: `${repo}/tree/main`,
+          editUrl: isProd ? `${repo}/tree/main` : undefined,
         },
         theme: {
           customCss: './src/css/custom.css',

netlify.toml

@@ -0,0 +1,6 @@
+[build]
+publish = "build"
+command = "npm run build:preview"
+
+[context.production]
+command = "npm run build:production"

package.json

@@ -3,6 +3,7 @@
   "version": "0.0.0",
   "description": "Resources provided by the CNCF Technical Documentation team.",
   "scripts": {
+    "_build": "docusaurus build",
     "_check:format:any": "npx prettier --check --ignore-path ''",
     "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)",
     "_check:format": "npx prettier --check .",
@@ -29,7 +30,9 @@
     "update:pkgs": "npx npm-check-updates -u",
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "build": "docusaurus build",
+    "build:preview": "npm run _build",
+    "build:production": "npm run _build",
+    "build": "BUILD_ENV=dev npm run _build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",

static/refcache.json

@@ -255,6 +255,14 @@
     "StatusCode": 206,
     "LastSeen": "2025-03-19T11:52:38.95612-04:00"
   },
+  "https://github.com/cncf/sandbox": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-22T19:39:31.8704-04:00"
+  },
+  "https://github.com/cncf/servicedesk": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-22T19:39:32.21738-04:00"
+  },
   "https://github.com/cncf/tag-app-delivery": {
     "StatusCode": 206,
     "LastSeen": "2025-03-19T11:52:40.942477-04:00"