executablebooks
Clarify Google Analytics configuration in Jupyter Book documentation
There needs to be more accurate Jupyter Book documentation regarding the configuration for enabling Google Analytics. The two sections provide different YAML configurations:
The documentation suggests using the following YAML configuration:
html:
analytics:
google_analytics_id: G-XXXXXXX
The default configuration example in this section is different:
html:
...
google_analytics_id : "" # A GA id that can be used to track book views.
It needs to be clarified which configuration should be used to enable Google Analytics correctly. The first example nests the google_analytics_id under html.analytics, while the second example directly places google_analytics_id under html.
Could the documentation be updated to clarify which configuration is correct, or, if both are valid, provide guidance on when to use each? This would help avoid confusion for users setting up Google Analytics tracking for their Jupyter Books.
It would appear (upon testing) that only the second one is correct. Are you up for updating the documentation?
@MortenHannemose, should I also change the default configuration file? Would you have any thoughts to share about it? This file is also different from the default config docs.
https://github.com/jupyter-book/jupyter-book/blob/608eca9608d3e03d419ef8a78ef6aef1817d4327/jupyter_book/default_config.yml#L58-L61
I'm sorry, I was testing on 1.0.2 (latest release), instead of on master.
After that release in
https://github.com/jupyter-book/jupyter-book/commit/fb16d16e2441cc62be24c7f6c20292648b65ccf4
the google_analytics_id was pulled into analytics, but that is only available on master. I suppose the right thing to do is to instead only update the default config.
Sorry, for sending you in the wrong direction.
That is no problem. I should have done my tests here, too. So, the point from the default config is that it is displayed from a yaml file, and I guess we have no control over what's being shown despite the default_config.yaml file.
Here is the raw content:
## Configuration defaults
Below is the full default configuration file.
Anything you set in your own `_config.yml` will be merged into these defaults before they are used to configure the build.
```{literalinclude} ../../jupyter_book/default_config.yml
:language: yaml
:class: full-width
On the master branch, the default_config.yaml seems okay but has not been released yet.
Based on the comment here https://github.com/jupyter-book/jupyter-book/issues/2194#issuecomment-2358570241 and the fact that we made a release in October, I believe that this is now resolved. Thanks for the conversation here to try and fix things!
