Add path option for plausible-analytics option

cderv · cderv · commit da2076bf84bd · 2025-10-13T17:38:09.000+02:00
diff --git a/news/changelog-1.9.md b/news/changelog-1.9.md
@@ -33,7 +33,7 @@ All changes included in 1.9:
 ### `website`
 
 - Algolia Insights now uses privacy-friendly defaults: `useCookie: false` with random session tokens when cookie consent is not configured. When `cookie-consent: true` is enabled, Algolia scripts are deferred and only use cookies after user grants "tracking" consent, ensuring GDPR compliance.
-- Add support for Plausible Analytics via `plausible-analytics` configuration option. Users can paste their Plausible script snippet directly from their Plausible dashboard.
+- Add support for Plausible Analytics via `plausible-analytics` configuration option. Users can either paste their Plausible script snippet directly in YAML or provide a path to a file containing the snippet using `plausible-analytics: { path: _plausible_snippet.html }`.
 
 ## `publish`
 
diff --git a/src/project/types/website/website-analytics.ts b/src/project/types/website/website-analytics.ts
@@ -5,6 +5,7 @@
  */
 import { Document } from "../../../core/deno-dom.ts";
 import { join } from "../../../deno_ral/path.ts";
+import { existsSync } from "../../../deno_ral/fs.ts";
 import { kLang, kTitle } from "../../../config/constants.ts";
 import { Format, Metadata } from "../../../config/types.ts";
 import { projectTypeResourcePath } from "../../../core/resources.ts";
@@ -28,6 +29,7 @@ const kVersion = "version";
 
 // Plausible analytics
 export const kPlausibleAnalytics = "plausible-analytics";
+const kPlausiblePath = "path";
 
 // Cookie consent properties
 export const kCookieConsent = "cookie-consent";
@@ -119,8 +121,26 @@ export function websiteAnalyticsScriptFile(
 
     // Plausible Analytics
     const plausibleSnippet = siteMeta[kPlausibleAnalytics];
-    if (plausibleSnippet && typeof plausibleSnippet === "string") {
-      scripts.push(plausibleSnippet);
+    if (plausibleSnippet) {
+      if (typeof plausibleSnippet === "string") {
+        // Inline snippet provided directly in YAML
+        scripts.push(plausibleSnippet);
+      } else if (typeof plausibleSnippet === "object") {
+        // Path to file containing snippet
+        const plausibleMeta = plausibleSnippet as Metadata;
+        const snippetPath = plausibleMeta[kPlausiblePath] as string;
+        if (snippetPath) {
+          const absolutePath = join(project.dir, snippetPath);
+          if (existsSync(absolutePath)) {
+            const snippetContent = Deno.readTextFileSync(absolutePath);
+            scripts.push(snippetContent);
+          } else {
+            throw new Error(
+              `Plausible Analytics snippet file not found: ${snippetPath}`,
+            );
+          }
+        }
+      }
     }
   }
 
diff --git a/src/resources/schema/definitions.yml b/src/resources/schema/definitions.yml
@@ -752,20 +752,45 @@
                       This is automatically detected based upon the `tracking-id`, but you may specify it.
         description: "Enable Google Analytics for this website"
       plausible-analytics:
-        schema: string
+        anyOf:
+          - string
+          - object:
+              closed: true
+              properties:
+                path:
+                  path:
+                    description: "Path to a file containing the Plausible Analytics script snippet"
+              required: [path]
         description:
-          short: "Enable Plausible Analytics for this website by inserting scrips snippets to add in site `<head>`"
+          short: "Enable Plausible Analytics for this website by providing a script snippet or path to snippet file"
           long: |
-            Enable Plausible Analytics for this website by pasting the script snippet from your Plausible dashboard.
+            Enable Plausible Analytics for this website by pasting the script snippet from your Plausible dashboard,
+            or by providing a path to a file containing the snippet.
 
             Plausible is a privacy-friendly, GDPR-compliant web analytics service that does not use cookies and does not require cookie consent.
 
+            **Option 1: Inline snippet**
+
+            ```yaml
+            website:
+              plausible-analytics: |
+                <script async src="https://plausible.io/js/script.js"></script>
+            ```
+
+            **Option 2: File path**
+
+            ```yaml
+            website:
+              plausible-analytics:
+                path: _plausible_snippet.html
+            ```
+
             To get your script snippet:
 
             1. Log into your Plausible account at <https://plausible.io>
             2. Go to your site settings
             3. Copy the JavaScript snippet provided
-            4. Paste it here
+            4. Either paste it directly in your configuration or save it to a file
 
             For more information, see <https://plausible.io/docs/plausible-script>
       announcement:
diff --git a/tests/docs/smoke-all/website/plausible-analytics-path/.gitignore b/tests/docs/smoke-all/website/plausible-analytics-path/.gitignore
@@ -0,0 +1,4 @@
+/.quarto/
+/_site/
+
+**/*.quarto_ipynb
diff --git a/tests/docs/smoke-all/website/plausible-analytics-path/_plausible_snippet.html b/tests/docs/smoke-all/website/plausible-analytics-path/_plausible_snippet.html
@@ -0,0 +1,5 @@
+<script async src="https://plausible.io/js/pa-FROMFILE99.js"></script>
+<script>
+  window.plausibleFile=window.plausibleFile||function(){(plausibleFile.q=plausibleFile.q||[]).push(arguments)};
+  plausibleFile.init()
+</script>
diff --git a/tests/docs/smoke-all/website/plausible-analytics-path/_quarto.yml b/tests/docs/smoke-all/website/plausible-analytics-path/_quarto.yml
@@ -0,0 +1,7 @@
+project:
+  type: website
+
+website:
+  title: "Plausible Path Test"
+  plausible-analytics:
+    path: _plausible_snippet.html
diff --git a/tests/docs/smoke-all/website/plausible-analytics-path/index.qmd b/tests/docs/smoke-all/website/plausible-analytics-path/index.qmd
@@ -0,0 +1,14 @@
+---
+title: "Plausible Path Test"
+_quarto:
+  tests:
+    html:
+      ensureHtmlElements:
+        -
+          - 'script[async][src="https://plausible.io/js/pa-FROMFILE99.js"]'
+      ensureFileRegexMatches:
+        - ['window\.plausibleFile', 'plausibleFile\.init']
+---
+
+This test verifies that Plausible Analytics with a path to an external file
+loads the snippet correctly from the file.

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +/.quarto/
 +/_site/
++
 +**/*.quarto_ipynb