From 795c4b5c351618d4338b94620afc06c6ab54f148 Mon Sep 17 00:00:00 2001
From: Richard Darst <rkd@zgib.net>
Date: Tue, 15 Nov 2022 11:43:39 +0200
Subject: [PATCH] DOCS: document an easier method of plausible analytics
(#1867)
- More direct injection of plausible.io analytics, using nothing but
a standard Sphinx option.
- I have tested this in the jupyter-book docs. This solution uses `<script
defer="defer" ...>` instead of `<script defer ...>`, but the
plausible people say it should be the same. The advantage here is
that the configuration is more simple and stardard.
- Apparently this will also be possible by the pydata sphinx theme,
it's up to you all if you prefer theme-based or standard config
based. Feel free to close this PR if you would rather sphinx-based.
---
docs/advanced/html.md | 24 +++++-------------------
1 file changed, 5 insertions(+), 19 deletions(-)
diff --git a/docs/advanced/html.md b/docs/advanced/html.md
index e508839f..95897f0c 100644
--- a/docs/advanced/html.md
+++ b/docs/advanced/html.md
@@ -142,27 +142,13 @@ html:
## Use Plausible Analytics
[Plausible Analytics](https://plausible.io) is a lightweight, open source, [privacy-focused](https://plausible.io/privacy-focused-web-analytics) analytics service that can be used as a more ethical alternative (or, in addition to) to Google Analytics.
-The requirement to use Plausible.io is to add a snippet into the `<head>` section of every html page:
-```
-<script defer data-domain="YOUR-DATA-DOMAIN" src="https://plausible.io/js/plausible.js"></script>
-```
-
-% TODO: When we update our dependency to PyData 0.10 there will be native support for Plausible
-% ref: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#plausible-analytics
-It is not yet possible in JupyterBook to directly inject `html` code into the site `<head>`, but it is possible to add [](custom-assets).
-To use Plausible Analytics in your JupyterBook, add this code into an arbitrarily-named `.js` file in the `_static` directory (create the directory in the root of your book if it does not already exist):
-
-```javascript
-var script = document.createElement('script');
-script.defer = true;
-script.src = "https://plausible.io/js/script.js";
-script.dataset.domain = "YOUR-DATA-DOMAIN";
+You can do this by adding the following in your configuration file:
-// optional if using proxy, see Plausible.io documentation for more about this
-// script.dataset.api = 'https://yourproxy.com/api/event';
-
-document.getElementsByTagName('head')[0].appendChild(script);
+```yaml
+sphinx:
+ config:
+ html_js_files: [ ['https://plausible.io/js/script.js', {'defer': 'defer', 'data-domain': 'yourdomain.com'}] ]
```
This should inject the appropriate code into the `<head>` via javascript, and you will be able to get analytics on your website through either the commercial company-hosted dashboard, or a [self-hosted instance](https://plausible.io/docs/self-hosting).
--
GitLab