bids-specification
bids-specification copied to clipboard
bids-standard
[ENH] Extensive use of definition hyperlinks
Originally listed in Lestropie/bids-specification#1, but warrants its own listing.
The theory is that if there exists within the specification a strict list of definitions, with centralised precise definitions of terms, then any usages of those terms elsewhere in the specification could use a hyperlink back to the precise definition.
It would be preferable if there were some solution that would minimise the length of code necessary within the raw .md files every time such a link is created; i.e. not having to do a full-length relative-path hyperlink every time the word "subject" or "session" or "entity" is used.
(Even better would be e.g. a tooltip that would pop up when hovering the mouse over the term; but don't know if there exists a solution for such that would be portable across different rendering targets)
Also see https://github.com/bids-standard/bids-specification/pull/923#issuecomment-990094903.
I have tried using md-tooltips and md-tooltips-link in conjunction with the mkdocs-macros-generated glossary proposed in #923 on a local branch, but the tooltips aren't indexing the glossary. I assume the glossary page is created after the tooltip links, or something. One solution might be to create the macros-generated content as some kind of pre-serve step instead, but I'm not sure how to do that.
crosslinking to another issue where this came up: https://github.com/bids-standard/bids-specification/issues/612#issuecomment-751781384
How do folks feel about the following patterns for links?
- Link to metadata field "Anaesthesia":
:metadata:`Anaesthesia` - Link to suffix "T1w":
:suffixes:`T1w` - Link to the MRI-specific definition of the metadata field AnatomicalLandmarkCoordinates:
:metadata:`AnatomicalLandmarkCoordinates <AnatomicalLandmarkCoordinates__mri>`- This would hopefully end up with a hyperlink/tooltip to with the string "AnatomicalLandmarkCoordinates" but targeting the specific definition we've requested.
I am confident I can write the Python function necessary to replace these patterns with hyperlinks in the markdown files, but I don't know how to run code on entire markdown files (as opposed to individual function calls with macros) as part of the build and/or serve processes. Is there a plugin for that?