Skip to content

Remove legacy Universal Analytics snippet from built-in themes - #84

Merged
shenxianpeng merged 2 commits into
mainfrom
claude/mkdocs-issue-4167-15dhse
Aug 12, 2026
Merged

shenxianpeng merged 2 commits into
mainfrom
claude/mkdocs-issue-4167-15dhse

Conversation

@shenxianpeng

Copy link
Copy Markdown
Member

Google shut down Universal Analytics in 2023, so the analytics.js snippet emitted by the built-in themes when the long-deprecated google_analytics config option was set has been sending visitor data to a dead service. This removes the snippet from both the mkdocs and readthedocs themes.

The google_analytics option itself remains accepted so that existing configs and third-party themes that read it keep working, but its deprecation warning now states that it has no effect on the built-in themes:

WARNING - Config value 'google_analytics': The configuration option google_analytics is
          deprecated and no longer has any effect: Google shut down Universal Analytics,
          and the built-in themes no longer include the legacy 'analytics.js' snippet.
          Use your theme's 'analytics' options (e.g. 'analytics.gtag' for Google
          Analytics 4) or override the 'analytics' template block instead.

Builds with --strict fail on the warning, as before. The modern theme.analytics.gtag (Google Analytics 4) option is unchanged.

Also adds a documentation example under "Overriding Template Blocks" showing how to plug in any analytics service by overriding the analytics block — the approach the upstream issue recommends.

Verified by building sites with both themes: with google_analytics set, output contains no analytics scripts and the warning above is emitted; with analytics.gtag set, the gtag snippet is still rendered. Build/theme/config test suites pass (394 tests).

Related Issue

Addresses upstream mkdocs/mkdocs#3630 (also related upstream: mkdocs/mkdocs#1794, mkdocs/mkdocs#2101).

Checklist

  • New tests added for new behavior (if applicable) — removal only; existing suites cover the themes and config
  • Documentation updated (if applicable)
  • Release notes docs/about/release-notes.md updated (if applicable)

🤖 Generated with Claude Code

https://claude.ai/code/session_018Hw7x9BxxpuKiLkzjLczp9


Generated by Claude Code

Google shut down Universal Analytics in 2023, so the 'analytics.js'
snippet emitted by the built-in themes when the long-deprecated
'google_analytics' config option was set has been sending visitor data
to a dead service. Remove the snippet from both the mkdocs and
readthedocs themes.

The 'google_analytics' option itself remains accepted so that existing
configs and third-party themes that read it keep working, but its
deprecation warning now states that it has no effect on the built-in
themes and points to the theme's 'analytics.gtag' option (Google
Analytics 4) or to overriding the 'analytics' template block. Builds
with '--strict' will fail on the warning, as before.

Also add a documentation example showing how to plug in any analytics
service by overriding the 'analytics' template block.

Addresses upstream issue mkdocs/mkdocs#3630.
@shenxianpeng
shenxianpeng merged commit 96ba00d into main Aug 12, 2026
21 checks passed
@shenxianpeng
shenxianpeng deleted the claude/mkdocs-issue-4167-15dhse branch August 12, 2026 11:16
@shenxianpeng shenxianpeng added the maintenance Targets chores, refactors and cleanups label Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintenance Targets chores, refactors and cleanups

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant