register-book-analytics

name	register-book-analytics
description	Wires Google Analytics 4 into an MkDocs Material site — creates a GA4 property, writes the Measurement ID into mkdocs.yml, verifies the tag, and deploys. Use when adding analytics to a textbook for the first time.

Register a Book with Google Analytics (MkDocs Material)

This skill registers a new MkDocs Material site as a Google Analytics 4 (GA4) property, captures the Measurement ID, writes it into mkdocs.yml, verifies the tag is injected, and commits/deploys.

Inputs to gather first

Read these from the repo and/or confirm with the user:

• Repo path – local folder containing mkdocs.yml (e.g. ~/Documents/ws/<book>).
• Site URL – usually site_url: in mkdocs.yml (e.g. https://dmccreary.github.io/<book>/).
• GA settings (defaults below, override if the user says otherwise):
  • Reporting time zone: US / Chicago (GMT-05:00 Chicago Time)
  • Business size: Small – 1 to 10 employees
  • Industry category: Jobs & Education (GA4 has no literal "Education and Training" option; "Jobs & Education" is the correct closest match — use it unless told otherwise)
  • Business objective: Understand web and/or app traffic (best fit for a docs site)

Open mkdocs.yml and confirm there is no existing extra.analytics block before starting.

Step 1 — Create the GA4 property (Claude in Chrome)

Requires the Claude in Chrome extension connected and the user logged into Google Analytics.

1. Navigate to https://analytics.google.com/analytics/web/ and wait for it to load.
2. Open Admin → Create property (or the "Create property" card on Home). This launches a 4-step wizard: Property creation → Business details → Business objectives → Data collection.
3. Property creation: enter the property name (match the book's site_name). Change the Reporting time zone — click the time-zone dropdown, type Chicago, select "(GMT-05:00) Chicago Time". Leave currency as USD. Click Next.
4. Business details: open the Industry category dropdown, type Education, select Jobs & Education. Select Small - 1 to 10 employees. Click Next.
5. Business objectives: check both the following:
   1. Understand web and/or app traffic
   2. View user engagement & retention

The action button on this step is labeled Create (not "Next") — click it to create the property.

Step 2 — Create the Web data stream and capture the Measurement ID

The number shown in the stream list (e.g. 15014865793) is the Stream ID, NOT the Measurement ID. The Measurement ID (format G-XXXXXXXXXX) only appears in the Google tag.

1. On the Data collection step choose Web as the platform.
2. In "Set up your web stream": set Website URL (protocol https:// + host/path, e.g. dmccreary.github.io/<book>/) and a Stream name (the book name). Leave Enhanced measurement on. Click Create & continue.
3. The "Set up a Google tag" panel appears. Read the Measurement ID from the snippet — it appears as gtag/js?id=G-XXXXXXXXXX and gtag('config', 'G-XXXXXXXXXX').
4. Verify the exact characters by zooming into the code block (don't trust a quick glance; 0/O, 1/I, Q/O are easy to misread). Record the G-... value.

Step 3 — Add the ID to mkdocs.yml

MkDocs Material reads analytics from extra.analytics. If an extra: block already exists, merge into it rather than adding a second extra: key (duplicate top-level keys break YAML).

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX
  # ...keep any existing schema/social/etc. keys here...

Step 4 — Build and verify the tag (do this before deploying)

Build to a temporary directory and confirm the ID is injected into the HTML:

cd <repo>
mkdocs build -q -d /tmp/site_verify        # mkdocs-material must be installed
grep -c "G-XXXXXXXXXX" /tmp/site_verify/index.html   # expect >= 1
grep -o "googletagmanager.com/gtag/js?id=G-XXXXXXXXXX" /tmp/site_verify/index.html

A non-zero count confirms Material picked up the analytics config.

Step 5 — Commit, push, deploy

cd <repo>
git add mkdocs.yml
git commit -m "Add Google Analytics property G-XXXXXXXXXX to mkdocs.yml"
git push origin main
mkdocs gh-deploy      # builds and pushes the site to the gh-pages branch

After deploy, optionally confirm the live tag: curl -s https://dmccreary.github.io/<book>/ | grep -o "G-XXXXXXXXXX".

Environment notes / known limitations

These matter when running inside the Cowork sandbox (vs. the user's own terminal):

• GitHub credentials: the Cowork Linux sandbox has no push credentials. git push and mkdocs gh-deploy (which pushes to gh-pages) will fail with "could not read Username for https://github.com". When this happens, do the GA registration, the mkdocs.yml edit, the build-verify, and the local git commit, then hand the user the exact git push / mkdocs gh-deploy commands to run in their own terminal.
• Mount delete restrictions: the sandbox mount may forbid deleting files. This can (a) break mkdocs build into the existing site/ dir (build to a temp dir instead, as in Step 4), and (b) leave stale .git/*.lock files after a commit. If you see unable to unlink .git/HEAD.lock / index.lock, tell the user to run rm -f .git/HEAD.lock .git/index.lock .git/objects/maintenance.lock before their next git command.
• Theme: verification requires pip install mkdocs-material if the sandbox only has base mkdocs.