linkml / linkml-project-cookiecutter

A cookiecutter for linkml projects. An equivalent of `linkml-ws new project-name`.
Creative Commons Zero v1.0 Universal
14 stars 16 forks source link

Issues with `google_analytics_gtag` field #23

Closed pkalita-lbl closed 1 year ago

pkalita-lbl commented 1 year ago

There are two issues with the google_analytics_gtag as far as I can tell.

  1. In the project template, that field is used to populate mkdocs.yml like so:
# mkdocs.yml
theme:
  name: material
  analytics:
    gtag: {{cookiecutter.google_analytics_gtag}}

However I don't think that's the correct way to configure analytics. When I build the docs in a generated project, I don't see the google_analytics_gtag value that I provided show up anywhere in the built doc pages. According to the mkdocs-material docs mkdocs.yml should contain something like this:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX
  1. I'm not sure it's smart to have a default value for google_analytics_gtag that appears to be a valid Google tag. If multiple projects accept the default value and publish their doc sites then analytics from multiple, unrelated sites would be publishing to the same analytics property. That's not a good thing. The only thing preventing that from happening is the misconfiguration outlined above.

I think we should either:

A) remove the google_analytics_gtag field, remove the analytics settings from mkdocs.yml, and assume users who want to set up analytics collection on their doc sites can figure it out B) remove the google_analytics_gtag field, fix the analytics settings in mkdocs.yml (including using property: G-XXXXXXXXXX) but keep it commented out with a note saying that block can be uncommented if they have a Google tag and want to collect analytics C) keep the google_analytics_gtag field, set the default to an empty string, fix the analytics settings in mkdocs.yml, but only include it if google_analytics_gtag is not empty.

I thing I'd slightly shy away from C because I think google_analytics_gtag is somewhat confusing for a new user and unfortunately you cannot currently add additional details to the prompt to explain what it is.

cmungall commented 1 year ago

I agree A or B is best, no string opinions

(I do want to make sure the repos we set up in our own projects have the tag though)