analytics: add Marlin SDK and migrate dropdown Heap markers

Introduces @docker/marlin-sdk-web-public for first-party pageview and
click analytics, bundled into scripts.js via Hugo's existing js.Build
pipeline. Config is emitted to window.__marlinConfig from head.html and
gated to prod/staging only.

Renames data-heap-id attributes on the markdown-dropdown buttons to
marlin-action so they are picked up by the SDK's auto-click tracking.

TODO: replace the REPLACE-ME endpoint placeholders in hugo.yaml with
the canonical Marlin ingestion URLs from the data-platform team.

TODO: heap.track() calls in youtube-script.html are left in place —
the public SDK exposes no equivalent track() method, so video
play/pause events cannot be migrated yet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dvdksn

assets/js/src/marlin.js

@@ -0,0 +1,19 @@
+import { Marlin, Environment } from "@docker/marlin-sdk-web-public";
+
+const config = window.__marlinConfig;
+
+if (config && config.apiKey && config.endpoint) {
+  try {
+    window.marlin = new Marlin({
+      endpoint: config.endpoint,
+      apiKey: config.apiKey,
+      site: "docs",
+      environment:
+        config.environment === "staging"
+          ? Environment.STAGING
+          : Environment.PROD,
+    });
+  } catch (err) {
+    console.warn("Marlin SDK init failed:", err);
+  }
+}

hugo.yaml

@@ -142,6 +142,16 @@ params:
     google: GTM-WL2QLG5
     onetrust: 65425fb0-7b36-4317-9f10-7b3e08039af0
     vwo: 723167
+    marlin:
+      # Public-write API keys for the Marlin analytics SDK.
+      apiKey:
+        prod: mrl_2nuEKUo5bzRv8GcDKeYjij4J4U--OLdN
+        stage: mrl_W14SGEQ7nYmBsAyjZPyOM-nlgE53E-vX
+      # TODO: replace placeholder endpoints with the canonical Marlin
+      # ingestion URLs from the data-platform team.
+      endpoint:
+        prod: https://REPLACE-ME.marlin.docker.com
+        stage: https://REPLACE-ME.marlin.staging.docker.com
 
   # Docs repository URL
   repo: https://github.com/docker/docs

layouts/_partials/head.html

@@ -67,6 +67,29 @@
   })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
   </script>
 {{ end }}
+{{- with site.Params.analytics.marlin -}}
+  {{- $apiKey := "" -}}
+  {{- $endpoint := "" -}}
+  {{- $env := "" -}}
+  {{- if hugo.IsProduction -}}
+    {{- $apiKey = .apiKey.prod -}}
+    {{- $endpoint = .endpoint.prod -}}
+    {{- $env = "prod" -}}
+  {{- else if eq hugo.Environment "staging" -}}
+    {{- $apiKey = .apiKey.stage -}}
+    {{- $endpoint = .endpoint.stage -}}
+    {{- $env = "staging" -}}
+  {{- end -}}
+  {{- if and $apiKey $endpoint -}}
+    <script>
+      window.__marlinConfig = {
+        apiKey: {{ $apiKey | jsonify }},
+        endpoint: {{ $endpoint | jsonify }},
+        environment: {{ $env | jsonify }}
+      };
+    </script>
+  {{- end -}}
+{{- end -}}
 {{/* preload Roboto Flex as it's a critical font: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload */}}
 <link
   href="/assets/fonts/RobotoFlex.woff2"

layouts/_partials/md-dropdown.html

@@ -2,7 +2,7 @@
   <div class="flex flex-wrap items-center gap-x-6 gap-y-2 text-sm">
     <button
       onclick="askGordon()"
-      data-heap-id="ask-gordon-button"
+      marlin-action="ask-gordon-button"
       class="inline-flex cursor-pointer items-center gap-1.5 text-gray-600 transition-colors hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100"
     >
       <span class="icon-svg icon-sm -translate-y-px">
@@ -13,7 +13,7 @@
 
     <button
       onclick="copyMarkdown()"
-      data-heap-id="copy-markdown-button"
+      marlin-action="copy-markdown-button"
       class="inline-flex cursor-pointer items-center gap-1.5 text-gray-600 transition-colors hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100"
     >
       <span class="icon-svg icon-sm">
@@ -27,7 +27,7 @@
 
     <button
       onclick="viewPlainText()"
-      data-heap-id="view-markdown-button"
+      marlin-action="view-markdown-button"
       class="inline-flex cursor-pointer items-center gap-1.5 text-gray-600 transition-colors hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100"
     >
       <span class="icon-svg icon-sm">
@@ -51,7 +51,7 @@
       .then((text) => {
         navigator.clipboard.writeText(text).then(() => {
           const button = document.querySelector(
-            '[data-heap-id="copy-markdown-button"]',
+            '[marlin-action="copy-markdown-button"]',
           );
           if (!button) return;
 

package-lock.json

@@ -17,6 +17,7 @@
     "@alpinejs/collapse": "3.15.8",
     "@alpinejs/focus": "3.15.8",
     "@alpinejs/persist": "3.15.8",
+    "@docker/marlin-sdk-web-public": "0.2.0",
     "@floating-ui/dom": "1.7.6",
     "@tailwindcss/cli": "4.2.1",
     "@tailwindcss/typography": "0.5.19",