From 3aa822a4e846c2eb9073c9b6ae258f03bf70604b Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 24 Apr 2025 06:04:10 -0400 Subject: [PATCH] Analytics docs rework: factor out UA-to-GA4 instructions, and more (#312) --- .htmltest.yml | 1 + docs/analytics/README.md | 23 +++++++++++++++ docs/{analytics.md => analytics/ua-to-ga4.md} | 28 ++++++------------- docusaurus.config.ts | 10 +++++-- netlify.toml | 6 ++++ package.json | 5 +++- static/refcache.json | 8 ++++++ 7 files changed, 58 insertions(+), 23 deletions(-) create mode 100644 docs/analytics/README.md rename docs/{analytics.md => analytics/ua-to-ga4.md} (92%) create mode 100644 netlify.toml diff --git a/.htmltest.yml b/.htmltest.yml index 8594ce7..84e17fd 100644 --- a/.htmltest.yml +++ b/.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 diff --git a/docs/analytics/README.md b/docs/analytics/README.md new file mode 100644 index 0000000..cc198c7 --- /dev/null +++ b/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 projects@cncf.io 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 diff --git a/docs/analytics.md b/docs/analytics/ua-to-ga4.md similarity index 92% rename from docs/analytics.md rename to docs/analytics/ua-to-ga4.md index 6ece103..79733ef 100644 --- a/docs/analytics.md +++ b/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 diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 96b5c27..2cb5443 100644 --- a/docusaurus.config.ts +++ b/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', diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000..cbdbceb --- /dev/null +++ b/netlify.toml @@ -0,0 +1,6 @@ +[build] +publish = "build" +command = "npm run build:preview" + +[context.production] +command = "npm run build:production" diff --git a/package.json b/package.json index cf6d672..3fc71a6 100644 --- a/package.json +++ b/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", diff --git a/static/refcache.json b/static/refcache.json index 1a96d40..1b5b4d9 100644 --- a/static/refcache.json +++ b/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"