From abc4cb8d158947de22d07797645689a9ae091eeb Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <xianpeng.shen@gmail.com>
Date: Sun, 18 Oct 2026 22:01:02 +0300
Subject: [PATCH 1/2] docs: add Google Analytics

- Send page views to the Google Analytics property that
  cpp-linter.github.io already uses. These docs share its origin, so
  one property covers the whole site.
- Tag maintainer visits with traffic_type=internal when the
  cpp-linter-internal flag is set (?internal=1 on any page of the
  site), so the Internal Traffic data filter can drop them.
- Title the 404 page "Page not found" so missing pages do not show up
  under the home page's title.
---
 cspell.config.yml        |  1 +
 docs/mkdocs.yml          |  6 ++++++
 docs/overrides/404.html  | 14 ++++++++++++++
 docs/overrides/main.html | 28 ++++++++++++++++++++++++++++
 4 files changed, 49 insertions(+)
 create mode 100644 docs/overrides/404.html
 create mode 100644 docs/overrides/main.html

diff --git a/cspell.config.yml b/cspell.config.yml
index 87526675..9b589e4a 100644
--- a/cspell.config.yml
+++ b/cspell.config.yml
@@ -43,6 +43,7 @@ words:
   - gitmodules
   - gnueabi
   - gnueabihf
+  - htmltitle
   - hustcer
   - imara
   - inlinehilite
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 83edad14..296ec385 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -22,6 +22,7 @@ nav:
 
 theme:
   name: material
+  custom_dir: overrides
   features:
     - navigation.top
     - content.tabs.link
@@ -77,6 +78,11 @@ extra:
       link: https://www.npmjs.com/package/@cpp-linter/cpp-linter
     - icon: simple/rust
       link: https://crates.io/crates/cpp-linter
+  # The same Google Analytics property as cpp-linter.github.io and the other
+  # cpp-linter docs, which all share that origin.
+  analytics:
+    provider: google
+    property: G-JKH4SXC7HC
 
 extra_css:
   - https://cpp-linter.github.io/stylesheets/shared.css
diff --git a/docs/overrides/404.html b/docs/overrides/404.html
new file mode 100644
index 00000000..40202e8b
--- /dev/null
+++ b/docs/overrides/404.html
@@ -0,0 +1,14 @@
+{% extends "main.html" %}
+
+{#-
+  Gives the 404 page a title of its own, so that missing pages are not counted
+  under the home page's title in Google Analytics.
+-#}
+
+{% block htmltitle %}
+  <title>Page not found - {{ config.site_name }}</title>
+{% endblock %}
+
+{% block content %}
+  <h1>404 - Not found</h1>
+{% endblock %}
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
new file mode 100644
index 00000000..ee13f5af
--- /dev/null
+++ b/docs/overrides/main.html
@@ -0,0 +1,28 @@
+{% extends "base.html" %}
+
+{#-
+  Visits from the maintainers are tagged so that the Internal Traffic data
+  filter in Google Analytics can drop them. These docs share the
+  cpp-linter.github.io origin with the organization site, which sets the flag:
+  opening any page there or here with ?internal=1 stores it in localStorage and
+  ?internal=0 removes it. While it is there, every event carries
+  traffic_type=internal. It runs before Material's own snippet, so the setting
+  is queued ahead of the first page_view.
+-#}
+
+{% block analytics %}
+  {% if config.extra.analytics %}
+    <script>
+      try {
+        var param = new URLSearchParams(location.search).get("internal");
+        if (param === "1") localStorage.setItem("cpp-linter-internal", "1");
+        if (param === "0") localStorage.removeItem("cpp-linter-internal");
+        if (localStorage.getItem("cpp-linter-internal") === "1") {
+          window.dataLayer = window.dataLayer || [];
+          (function () { dataLayer.push(arguments); })("set", { traffic_type: "internal" });
+        }
+      } catch (e) {}
+    </script>
+  {% endif %}
+  {{ super() }}
+{% endblock %}

From 973201d273a2780b05a3f3a1a9e6626f3e6adbab Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <xianpeng.shen@gmail.com>
Date: Sun, 18 Oct 2026 22:07:29 +0300
Subject: [PATCH 2/2] docs: say why the internal-traffic snippet ignores
 storage errors

---
 docs/overrides/main.html | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/overrides/main.html b/docs/overrides/main.html
index ee13f5af..9b77bf7d 100644
--- a/docs/overrides/main.html
+++ b/docs/overrides/main.html
@@ -21,7 +21,9 @@
           window.dataLayer = window.dataLayer || [];
           (function () { dataLayer.push(arguments); })("set", { traffic_type: "internal" });
         }
-      } catch (e) {}
+      } catch (e) {
+        // localStorage is unavailable when storage is blocked; the visit is then not tagged.
+      }
     </script>
   {% endif %}
   {{ super() }}