Plausible Analytics Integration
Add Plausible Analytics, a lightweight, cookie-free alternative to Google Analytics, to your documentation site.
Add Plausible Analytics to your documentation site for traffic data without cookies or cross-site tracking.
Plausible is open source and weighs under 1 KB. Most jurisdictions don't require a cookie consent banner for it.
If you do need consent gating (or you also run GA, GTM, or Crisp), see Cookie Consent.
Pick one of two setups:
| Setup | Use when | Field |
|---|---|---|
| Standard | You're on Plausible's free plan, or paid without proxy needs | domain |
| Proxy script | You're on a paid plan and want to bypass ad blockers | scriptUrl |
Standard Setup (domain)
Most sites use this setup. Register your site in Plausible and pass the domain.
Sign up for Plausible
Create an account at Plausible Analytics and add your documentation site domain (e.g., docs.example.com).
Add the domain to docs.json
{
"name": "My Docs",
"integrations": {
"plausible": {
"domain": "docs.example.com"
}
}
}Use the exact domain you registered: docs.example.com, not www.docs.example.com.
Self-hosted server
If you run the Community Edition, add the server field. It points the script and event API to your instance:
{
"name": "My Docs",
"integrations": {
"plausible": {
"domain": "docs.example.com",
"server": "https://analytics.example.com"
}
}
}server only works with domain. Proxy scripts handle their own routing.
Proxy Script Setup (scriptUrl)
Plausible's paid plans offer proxy scripts with a unique filename (like pa-XXXXX.js). These bypass most ad blockers. The script URL doesn't match common filter lists.
Get your proxy script URL
In your Plausible site settings, find the proxy script section and copy the full URL. It looks like https://plausible.io/js/pa-XXXXX.js.
Add the script URL to docs.json
{
"name": "My Docs",
"integrations": {
"plausible": {
"scriptUrl": "https://plausible.io/js/pa-XXXXX.js"
}
}
}Leave out domain and server. The script ID carries your site identity. Plausible's CDN routes requests internally.
Verifying the Installation
Check that data arrives:
- Trigger a rebuild of your docs
- Visit your live documentation site
- Check your Plausible dashboard. Your visit should appear within a few seconds.
- Or open DevTools, go to the Network tab, and look for a request to
plausible.io/js/script.js(standard) or yourpa-XXXXX.jsscript (proxy)
Plausible shows data in real time, with no waiting period like Google Analytics.
Configuration Reference
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | One of domain or scriptUrl | Your site's domain as registered in Plausible. Used as the data-domain attribute on the script tag. |
scriptUrl | string | One of domain or scriptUrl | Full URL to a Plausible paid proxy script (pa-XXXXX.js). Site identity is baked into the script. No domain field is needed. |
server | string | No | URL of a self-hosted Plausible server. Only used with domain, not scriptUrl. |
Troubleshooting
The usual cause is the domain. It must match what you registered in Plausible exactly (docs.example.com, not www.docs.example.com).
If the domain looks right:
- Rebuild your docs. Configuration changes only take effect after a new build.
- Check for ad blockers. Some browser extensions block analytics scripts, including Plausible. If that's the cause, switch to the proxy script setup.
- Inspect the page source for a
<script>tag withdata-domain(standard) or yourpa-XXXXX.jsfilename (proxy). If it's not there, the config didn't apply.
Register the domain your readers visit. If your docs are at docs.example.com, use that as the domain, not your root domain.
Switch to the proxy script setup. The unique filename bypasses most ad blocker filter lists. Self-hosting also gets past ad blockers. The script loads from your own domain.
Use domain if you're on the free plan or don't care about ad blockers. Use scriptUrl if you're on a paid plan and want maximum tracking coverage. Don't set both.