Warning after following docs' instructions for configuring analytics

[santisoler]

Hi! First of all, thanks a lot for developing Myst! I really appreciate the effort all of you put into it :rocket:

Description

After following the instructions on how to configure analytics, I get a warning stating that the analytics_plausible key should be nested under "options". I suspect the instructions in the docs are outdated and should be updated.

Here I leave a minimal example that can reproduce this warning.

1. Clone the quickstart repo:

   git clone https://github.com/executablebooks/mystmd-quickstart.git
   cd mystmd-quickstart

2. Create a new myst.yml file that includes a line configuring the analytics through the analytics_plausible key nested inside site, as the docs instructs:

   # See docs at: https://mystmd.org/guide/frontmatter
   version: 1
   project:
    # title:
    # description:
    keywords: []
    authors: []
    github: https://github.com/executablebooks/mystmd-quickstart
    # bibliography: []
   site:
    template: book-theme
    # title:
    # options:
    #   logo: site_logo.png
    nav: []
    actions:
      - title: Learn More
        url: https://mystmd.org/guide
    domains: []
    # Add analytics
    analytics_plausible: mystmd.org # Domain(s) to track

3. Build the website with myst:

   myst build

The last command gives the following output:

⚠️  myst.yml extra site options should be nested under "options" key: analytics_plausible                
🌎 Building MyST site                                                                                   
📖 Built README.md in 76 ms.                                                                            
📖 Built 01-paper.md in 73 ms.                                                                          
📖 Built 02-notebook.ipynb in 65 ms.                                                                    
⚠️  _build/site/public/citations-bde29672608abb7ee2680f5e8412d1d1.png Could not convert from image _build/site/public/citations-bde29672608abb7ee2680f5e8412d1d1.png to webp:                                    
cwebp is required                                                                                       

⚠️  _build/site/public/equations-e661c8f673c584829298052d9365ed23.gif Could not convert from image _build/site/public/equations-e661c8f673c584829298052d9365ed23.gif to webp:                                    
gif2webp is required                                                                                    

⚠️  _build/site/public/interactive-cbc72f0575cfb35edd250daed1a14f7a.gif Could not convert from image _build/site/public/interactive-cbc72f0575cfb35edd250daed1a14f7a.gif to webp:                                
gif2webp is required                                                                                    

⚠️  _build/site/public/structured-data-455ad46debdcf2582054b9cef93ae0ea.gif Could not convert from image _build/site/public/structured-data-455ad46debdcf2582054b9cef93ae0ea.gif to webp:                        
gif2webp is required                                                                                    

⚠️  _build/site/public/pdf-two-column-11c0c26a3b4b51da1af8498eca260fde.png Could not convert from image _build/site/public/pdf-two-column-11c0c26a3b4b51da1af8498eca260fde.png to webp:                          
cwebp is required                                                                                       

⚠️  _build/site/public/citations-bde29672608abb7ee2680f5e8412d1d1.png Could not convert from image _build/site/public/citations-bde29672608abb7ee2680f5e8412d1d1.png to webp:                                    
cwebp is required                                                                                       

⚠️  _build/site/public/frontmatter-after-b2b4a3272457fa951bfce1b0e34963a3.png Could not convert from image _build/site/public/frontmatter-after-b2b4a3272457fa951bfce1b0e34963a3.png to webp:                    
cwebp is required                                                                                       

⚠️  _build/site/public/export-pdf-1be7d0647a9ef07895cb8ff0df302ad5.png Could not convert from image _build/site/public/export-pdf-1be7d0647a9ef07895cb8ff0df302ad5.png to webp:                                  
cwebp is required                                                                                       

📚 Built 3 pages for project in 400 ms.                                                                 
🔍 Querying template metadata from https://api.mystmd.org/templates/site/myst/book-theme                
🐕 Fetching template from https://github.com/myst-templates/book-theme/archive/refs/heads/main.zip      
💾 Saved template to path _build/templates/site/myst/book-theme

Myst is complaining about having analytics_plausible nested under site and not under options.

I get this warning on myst=v1.1.37.

Proposed solution

If I'm right and the documentation is outdated, then we should update it.

For configuring Google Analytics it should be:

version: 1
site:
  options:
    analytics_google: UA-XXXXX # Measurement ID or Tracking ID

And for Plausible:

version: 1
site:
  options:
    analytics_plausible: mystmd.org # Domain(s) to track

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[jonmatthis]

Bumping this - Warnings happening on Windows 11 when following the quickstart tutorial.

(mystmd-env) (jonma-py3.12) C:\Users\jonma\github_repos\jonmatthis\jonmatthis\mystmd-quickstart>myst start

(mystmd-env) (jonma-py3.12) C:\Users\jonma\github_repos\jonmatthis\jonmatthis\mystmd-quickstart>⚠️  01-paper.md:69 unexpected option "citations" provided for directive: figure
📖 Built README.md in 48 ms.
🪄  Linked 2 DOIs from doi.org in 12 ms for 01-paper.md
📖 Built 01-paper.md in 180 ms.
📖 Built 02-notebook.ipynb in 172 ms.
⚠️  _build\site\public\citations-9372b38b62969846117543a98cd596eb.png Could not convert from image _build\site\public\citations-9372b38b62969846117543a98cd596eb.png to webp:
cwebp is required

⚠️  _build\site\public\equations-8e9e10125373a80f9a4e043f169b4184.gif Could not convert from image _build\site\public\equations-8e9e10125373a80f9a4e043f169b4184.gif to webp:
gif2webp is required

⚠️  _build\site\public\interactive-b2b7132f7d7e84737cbf94bc50d93f0d.gif Could not convert from image _build\site\public\interactive-b2b7132f7d7e84737cbf94bc50d93f0d.gif to webp:
gif2webp is required

⚠️  _build\site\public\structured-data-01d89429bc1457d7993397669afb8dd1.gif Could not convert from image _build\site\public\structured-data-01d89429bc1457d7993397669afb8dd1.gif to webp:
gif2webp is required

⚠️  _build\site\public\pdf-two-column-5a12d68b5a04a07b022f3b1a724f7a6e.png Could not convert from image _build\site\public\pdf-two-column-5a12d68b5a04a07b022f3b1a724f7a6e.png to webp:
cwebp is required

⚠️  _build\site\public\frontmatter-after-0957e0de582115169b19844777d48588.png Could not convert from image _build\site\public\frontmatter-after-0957e0de582115169b19844777d48588.png to  webp:
cwebp is required

⚠️  _build\site\public\export-pdf-5f2372877f1af1b20f8b4e7dd327e857.png Could not convert from image _build\site\public\export-pdf-5f2372877f1af1b20f8b4e7dd327e857.png to webp:
cwebp is required

⚠️  _build\site\public\citations-9372b38b62969846117543a98cd596eb.png Could not convert from image _build\site\public\citations-9372b38b62969846117543a98cd596eb.png to webp:
cwebp is required

📚 Built 3 pages for project in 865 ms.

        ✨✨✨  Starting Book Theme  ✨✨✨

[agoose77]

This can be closed as our documentation is up to date! @jonmatthis your warnings are about missing cwebp and a figure directive, which is a different problem. What are you unsure about? :)

[jonmatthis]

@jonmatthis your warnings are about missing cwebp and a figure directive, which is a different problem. What are you unsure about? :)

Ok, thank you! How do I fix the 'missing cwebp' thing? Who is missing it? Python? Node? Is it an OS thing (I'm on Windows 11)?

EDIT - Nvm, figured it out!

Installed these webp binaries and added them to my path and the warnings went away: https://developers.google.com/speed/webp/download

[agoose77]

How do I fix the 'missing cwebp' thing?

This is a great example of how we can improve our error messages.

cwebp is a NodeJS package that packages bindings the webp library. You can get webp from nixpkgs, conda-forge, etc!

[jonmatthis]

cwebp is a NodeJS package that packages the webp library.

Can that package be added as a dependency to whichever npm package.json file is handling the NodeJS install?

[agoose77]

Ah, apologies; I was out when writing that message. The NodeJS packages is just the bindings; the binaries need to be on the host system.