document new cookie behavior for algolia

See quarto-dev/quarto-cli#13525

Author: cderv

docs/websites/website-search.qmd

@@ -167,7 +167,34 @@ website:
       analytics-events: true
 ```
 
-You can confirm that events are being properly sent to Algolia using the [Event Debugger](https://www.algolia.com/events/debugger). Note that the click and conversion events use cookies to maintain an anonymous user identifier---if [cookie consent](website-tools.qmd#cookie-consent) is enabled, search events will only be enabled if cookie consent has been granted.
+You can confirm that events are being properly sent to Algolia using the [Event Debugger](https://www.algolia.com/events/debugger).
+
+#### Cookie Consent and User Tracking
+
+Algolia Insights uses user tokens to track click and conversion events. By default, Quarto uses a **privacy-first approach** that does not store cookies:
+
+- **Default behavior (no cookies)**: A random session token is generated for each browser session. This allows tracking of search interactions during a single visit without storing persistent cookies. This default is compliant with privacy regulations like GDPR.
+
+- **Persistent tracking (with cookies)**: To track users across multiple sessions, you must enable [cookie consent](website-tools.qmd#cookie-consent). When cookie consent is enabled, Algolia will only use cookies after the user grants "tracking" consent:
+
+``` yaml
+website:
+  cookie-consent: true
+  search:
+    algolia:
+      index-name: <my-index-name>
+      application-id: <my-application-id>
+      search-only-api-key: <my-search-only-api-key>
+      analytics-events: true
+```
+
+With this configuration, the Algolia Insights API will use cookies to maintain an anonymous user identifier across sessions, but only after the user has explicitly granted consent.
+
+::: {.callout-note}
+## Privacy and Compliance
+
+The default session-only tracking provides meaningful analytics about search usage patterns while respecting user privacy. Enabling persistent cookie tracking may require compliance with privacy regulations in your jurisdiction, which is why Quarto requires explicit configuration of cookie consent.
+:::
 
 ### Advanced Configuration
 

docs/websites/website-tools.qmd

@@ -258,7 +258,7 @@ If you choose `none` for storage, this will have the following effects:
 
 Quarto includes the ability to request cookie consent before enabling scripts that set cookies, using [Cookie Consent](https://www.cookieconsent.com).
 
-The user's cookie preferences will automatically control [Google Analytics] (if enabled) and can be used to control custom scripts you add as well (see [Custom Scripts and Cookie Consent]). You can enable the default request for cookie consent using the following:
+The user's cookie preferences will automatically control [Google Analytics] and [Algolia search analytics](/docs/websites/website-search.qmd#algolia-insights) (if enabled) and can be used to control custom scripts you add as well (see [Custom Scripts and Cookie Consent]). You can enable the default request for cookie consent using the following:
 
 ``` yaml
 website:
@@ -313,8 +313,16 @@ website:
   google-analytics:
     tracking-id: "G-XXXXXXX"
     anonymize-ip: true
+  search:
+    algolia:
+      index-name: <my-index-name>
+      application-id: <my-application-id>
+      search-only-api-key: <my-search-only-api-key>
+      analytics-events: true
 ```
 
+Note that with cookie consent enabled, both Google Analytics and Algolia search analytics will only use cookies after the user has granted "tracking" consent. Without cookie consent enabled, Algolia will use session-only tracking without cookies. See [Algolia Insights](/docs/websites/website-search.qmd#algolia-insights) for more details.
+
 ### Cookie Preferences
 
 In addition to requesting consent when a new user visits your website, Cookie Consent will also add a cookie preferences link to the footer of the website. You can control the text of this link using `prefs-text`. If you would rather position this link yourself, just add a link with the id `#open_preferences_center` to the website and Cookie Consent will not add the preferences link to the footer. For example: