Merge pull request #1805 from quarto-dev/plausible-analytics

cderv · web-flow · commit 74f8b9e69cb7 · 2025-10-15T12:01:33.000+02:00
diff --git a/docs/websites/website-tools.qmd b/docs/websites/website-tools.qmd
@@ -211,7 +211,70 @@ image: false
 ---
 ```
 
-## Google Analytics
+## Analytics
+
+### Plausible Analytics
+
+[Plausible Analytics](https://plausible.io/) is a lightweight, open-source, and privacy-friendly alternative to Google Analytics. Plausible is designed with privacy as a core principle: it doesn't use cookies, is GDPR compliant by default, and all data is processed anonymously.
+
+To add Plausible Analytics to your Quarto website:
+
+1. Sign up at [plausible.io](https://plausible.io/) and add your website to your account.
+2. In your Plausible dashboard, navigate to your site's settings.
+3. Go to the "Site Installation" section and click "Review Installation" to get your unique tracking snippet.
+4. Copy the complete script snippet provided by Plausible from your dashboard.
+5. Add it to your `_quarto.yml` configuration file.
+
+You can provide the Plausible snippet in two ways:
+
+**Option 1: Inline snippet**
+
+Paste the snippet directly in your `_quarto.yml` configuration file under the `plausible-analytics` key. Use the `|` character after the key to preserve line breaks in the snippet:
+
+``` yaml
+website:
+  plausible-analytics: |
+    <script async src="https://plausible.io/js/pa-XXXXXX.js"></script>
+    <script>
+      window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
+      plausible.init()
+    </script>
+```
+
+**Option 2: File path**
+
+Save the snippet to a file (e.g., `_plausible_snippet.html`) and provide the path:
+
+``` yaml
+website:
+  plausible-analytics:
+    path: _plausible_snippet.html
+```
+
+The script will automatically be included in the `<head>` of every page on your website. **Important:** Make sure to copy and paste the complete snippet exactly as provided by Plausible - the example above shows the typical structure, but your actual snippet will have a unique tracking code instead of `XXXXXX`.
+
+::: {.callout-tip}
+The snippet from your Plausible dashboard may include multiple `<script>` tags and initialization code. Copy the entire snippet as-is - don't modify or simplify it. Using the file path option can be useful if you want to keep the snippet separate from your configuration or if you need to update it frequently.
+:::
+
+#### Optional Enhanced Measurements
+
+Plausible offers optional enhanced measurements that you can enable directly in your site settings dashboard (such as outbound link tracking, file downloads, etc.). When you enable these features in Plausible, your tracking snippet will be automatically updated in your dashboard. Simply copy the updated snippet and replace it in your `_quarto.yml` configuration.
+
+For more information about available enhanced measurements and configuration options, see the [Plausible script documentation](https://plausible.io/docs/plausible-script).
+
+#### Privacy Benefits
+
+Unlike traditional analytics solutions, Plausible Analytics:
+
+- **Uses no cookies**: Plausible doesn't use cookies or generate any persistent identifiers, so no cookie consent banners are needed
+- **Is GDPR compliant**: All visitor data is anonymized and processed in the EU
+- **Is lightweight**: The script is under 1 KB, significantly smaller than Google Analytics
+- **Has no cross-site tracking**: Plausible doesn't track users across different websites
+
+Because Plausible is privacy-friendly by default, you typically don't need to implement [Cookie Consent] when using it (though you should verify this with your own privacy requirements).
+
+### Google Analytics
 
 You can add [Google Analytics](https://analytics.google.com/) to your website by adding a `google-analytics` key to your `_quarto.yml` file. In its simplest form, you can just pass your Google Analytics tracking Id (e.g. `UA-xxxxxxx`) or Google Tag measurement Id (e.g. `G-xxxxxxx`) like:
 
@@ -242,7 +305,7 @@ In addition to this basic configuration, you can exercise more fine grained cont
 
 : {tbl-colwidths="[20,80]"}
 
-### Storage
+#### Storage
 
 Google Analytics uses cookies to distinguish unique users and sessions. If you choose to use cookies to store this user data, you should consider whether you need to enable [Cookie Consent] in order to permit the viewer to control any tracking that you enable.
 
