Feature Request: Documentation usability enhancement: give more items anchors for deep-linking

[gdevenyi]

Right now, if I want to point someone at a particular entry in the spec, such as:
SliceEncodingDirection

on the page
https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html

I can't do so because there's no anchor.

I'd like to suggest the TOC go one level deeper and actually have anchors available for the individual entries.

[Remi-Gau]

For metadata like this, the best current way to do it would be to use the glossary:

https://bids-specification.readthedocs.io/en/stable/99-appendices/14-glossary.html#sliceencodingdirection-metadata

[Remi-Gau]

Also I think that given the way mkdocs work, adding levels to the TOC would not be the way to do it but I may wrong.

[effigies]

The glossary loses the surrounding context, including requirement level which is not inherent to the term (some metadata is required for some files and not for others), but for defining terms it's quite useful.

I suppose we could add <a name=""></a> anchors when rendering tables, e.g. <a name="SliceEncodingDirection">SliceEncodingDirection</a> <a href="#SliceEncodingDirection">(link)</a>:

Key Name	Requirement Level	Data type	Description
SliceEncodingDirection (link)	...

Might want some kind of link symbol in place of the (link) text...

[gdevenyi]

For metadata like this, the best current way to do it would be to use the glossary:

bids-specification.readthedocs.io/en/stable/99-appendices/14-glossary.html#sliceencodingdirection-metadata

This is fine, but, the issue becomes, if I'm reading the docs, there's no link to the glossary (I didn't know it existed)

[tsalo]

Yes, that's something we're working on. See #954.