Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[ENH] Extensive use of definition hyperlinks #954

Open
Lestropie opened this issue Dec 10, 2021 · 5 comments · May be fixed by #2005
Open

[ENH] Extensive use of definition hyperlinks #954

Lestropie opened this issue Dec 10, 2021 · 5 comments · May be fixed by #2005
Labels
formatting Aesthetics and formatting of the spec schema Issues related to the YAML schema representation of the specification. Patch version release.

Comments

@Lestropie
Copy link
Collaborator

Originally listed in Lestropie#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)
@tsalo
Copy link
Member

tsalo commented Dec 10, 2021

Also see #923 (comment).

@tsalo
Copy link
Member

tsalo commented Dec 13, 2021

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.

@tsalo tsalo added formatting Aesthetics and formatting of the spec schema Issues related to the YAML schema representation of the specification. Patch version release. labels Dec 14, 2021
@tsalo tsalo mentioned this issue Dec 20, 2021
Merged
@sappelhoff
Copy link
Member

crosslinking to another issue where this came up: #612 (comment)

@tsalo tsalo mentioned this issue Mar 24, 2022
Closed
@tsalo
Copy link
Member

tsalo commented Apr 1, 2022

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.

@tsalo tsalo mentioned this issue Apr 6, 2022
Closed
@tsalo
Copy link
Member

tsalo commented Aug 31, 2022

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?

@Remi-Gau Remi-Gau linked a pull request Dec 12, 2024 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
formatting Aesthetics and formatting of the spec schema Issues related to the YAML schema representation of the specification. Patch version release.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[ENH] use snippets to link to definitions Remi-Gau/bids-specification
3 participants
@Lestropie @tsalo @sappelhoff