Skip to content

Document plausible-analytics new config #1805

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cderv merged 4 commits into from
Oct 15, 2025
Merged

Document plausible-analytics new config #1805

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
89329af
Document `plausible-analytics` new config
cderv Oct 10, 2025
3f6e9ac
Group plausible and google analytics under same part
cderv Oct 10, 2025
1b6d361
@cwickham review
cderv Oct 13, 2025
abaa570
Add documentation for `path`
cderv Oct 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 65 additions & 2 deletions docs/websites/website-tools.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```
Comment on lines +234 to +242
Copy link
Collaborator

@cwickham cwickham Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see getting the right indentation will be a source of problems for users...another reason to offer a path entrypoint.

Copy link
Collaborator Author

@cderv cderv Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added support for path in quarto-dev/quarto-cli#13524

Can you review the modified version of this PR ?

Thank you !


**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:

Expand Down Expand Up @@ -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.

Expand Down