From 5fb270200af4dbbf1d2726d14bb44f8fc2e99efd Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <xianpeng.shen@gmail.com>
Date: Sun, 18 Oct 2026 21:50:12 +0300
Subject: [PATCH 1/2] docs: add Google Analytics and a descriptive home page
 title

- 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.
- Give the home page a title and description that say what the action
  does, instead of the site name and "Developer documentation from
  sources."
---
 cspell.config.yml        |  1 +
 docs/index.md            |  5 +++++
 docs/overrides/404.html  | 14 ++++++++++++++
 docs/overrides/main.html | 28 ++++++++++++++++++++++++++++
 mkdocs.yml               |  9 +++++++++
 5 files changed, 57 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 60279518..e7874c37 100644
--- a/cspell.config.yml
+++ b/cspell.config.yml
@@ -4,6 +4,7 @@ words:
   - Cachy
   - cppcoreguidelines
   - fontawesome
+  - htmltitle
   - hustcer
   - imgproxy
   - inlinehilite
diff --git a/docs/index.md b/docs/index.md
index dbc0e3d8..93387793 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,8 @@
+---
+title: clang-format and clang-tidy GitHub Action
+description: Run clang-format and clang-tidy on the C/C++ files a pull request changes, with annotations, review suggestions and a thread comment.
+---
+
 [file-annotations]: inputs-outputs.md#file-annotations
 [thread-comments]: inputs-outputs.md#thread-comments
 [step-summary]: inputs-outputs.md#step-summary
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 %}
diff --git a/mkdocs.yml b/mkdocs.yml
index 4401284a..b00af67f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -4,6 +4,9 @@ site_url: "https://cpp-linter.github.io/cpp-linter-action"
 repo_url: "https://github.com/cpp-linter/cpp-linter-action"
 repo_name: "cpp-linter/cpp-linter-action"
 edit_uri: "edit/main/docs/"
+# Theme overrides live in docs/ but are not pages.
+exclude_docs: |
+  overrides/
 nav:
   - index.md
   - inputs-outputs.md
@@ -16,6 +19,7 @@ nav:
 
 theme:
   name: material
+  custom_dir: docs/overrides
   features:
     - navigation.top
     - content.tabs.link
@@ -65,6 +69,11 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/cpp-linter/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

From 0ea91e2775e2279711e85982d0cbd7a78cdf965b Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <xianpeng.shen@gmail.com>
Date: Sun, 18 Oct 2026 22:07:24 +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() }}