[ENH] use snippets to link to definitions via tooltips

[Remi-Gau]

• closes https://github.com/bids-standard/bids-specification/issues/954

this is me trying things out, see if this is a viable option

[Remi-Gau]

@tsalo @Lestropie

• this seems to be a possible easy pure mkdocs solution to #954 using https://squidfunk.github.io/mkdocs-material/reference/tooltips/#tooltips

• in brief we can create a generic list of 'links' that will be appended to every page in the spec

• if those are prefixed with * then they are a tooltip

demo

https://www.dropbox.com/scl/fi/h1vmjihby032jdqismplg/Screencast-from-12-12-2024-15-45-05.webm?rlkey=rgm5qkjvlvtuj18e3fclchl11&dl=0

@effigies maybe also useful to have consistent set of links to external things across all pages:

$ grep -rni https://www.json.org/json-en.html src

src/modality-agnostic-files.md:549:[object]: https://www.json.org/json-en.html
src/modality-specific-files/genetic-descriptor.md:137:[object]: https://www.json.org/json-en.html
src/modality-specific-files/motion.md:240:[object]: https://www.json.org/json-en.html
src/derivatives/common-data-types.md:343:[object]: https://www.json.org/json-en.html
src/schema/objects/metadata.yaml:3360:    [Object](https://www.json.org/json-en.html)
src/common-principles.md:481:    [JSON object](https://www.json.org/json-en.html) described below; and
src/common-principles.md:515:in the form of a JSON [object](https://www.json.org/json-en.html)
src/appendices/hed.md:58:The JSON sidecar provides a [JSON object](https://www.json.org/json-en.html) of annotations for these categorical values.

Though I wonder how this part would play with the PDF generation.

[effigies]

IMO links are less useful in a PDF, so if this only affects the HTML spec, that seems fine.

[Remi-Gau]

The tool tip part would only be the html part. The second part about link summary would likely affect the pdf. Should try to confirm.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 82.44%. Comparing base (0a8f910) to head (251d812).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2005   +/-   ##
=======================================
  Coverage   82.44%   82.44%           
=======================================
  Files          17       17           
  Lines        1504     1504           
=======================================
  Hits         1240     1240           
  Misses        264      264           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.