links to spec sections sometimes broken when generated from schema

[sappelhoff]

For example, in the sessions-file section, look at the acq_time metadata row, and try clicking on the Units link.

It'll try to link you to https://bids-specification.readthedocs.io/02-common-principles.html#units, which doesn't exist --> it should be https://bids-specification.readthedocs.io/en/latest/02-common-principles.html#units (or "stable" instead of the "latest").

I think this may be due to the link being specified as .html instead of .md

bids-specification/src/schema/objects/columns.yaml

Line 20 in febae4f

Datetime should be expressed as described in [Units](/02-common-principles.html#units).

cc @tsalo

[tsalo]

Using .md won't work with "absolute" paths relative to the project folder, from what I can recall. I think we sort of touched on that in #762 (comment).

[sappelhoff]

I remember now - thanks for the reminder ...

So maybe we should carefully try it, and if it doesn't break anything it's fine.

seems like it did break something though :-(

[tsalo]

That's true. I guess we can look into four possible solutions:

1. Figure out how to get md hyperlinks working.
2. Use relative paths in the schema. I think this is a bad idea since the tables where the hyperlink ends up will vary.
3. Figure out how to include the version in the base URL that is prepended to the hyperlinks when everything's built.
4. Use the full hyperlink in the schema, rather than relative paths. This would mean hardcoding the version into the URL, and I think it's probably not the best solution.

Do you have any other ideas?

[sappelhoff]

Nope, but I think your "1" and "3" are reasonable 👍 Let's look whether we can get one of these implemented

related:

• Allow absolute URLs mkdocs/mkdocs#192 (comment)

[sappelhoff]

https://www.mkdocs.org/user-guide/writing-your-docs/#internal-links

it seems like from the MkDocs side, there is nothing we can do with "official tools"/features.

I think we could adopt this solution:

1. write absolute links like [i am a link]({{some_macro}}/absolute/link.md#heading), where we have a macro that does the following:
   1. detect the {{some_macro}} in the link
   2. figure out the path to the file where the macro call was detected
   3. return text like ../../.. such that we go from the file where the macro call was detected to the root of the project
   4. then combining the ../../.. and the /absolute/link.md#heading we get a "relative path" that should be properly worked on by Mcdocs

For example:

• This is the URL we put in the acq_time schema description
  • [Units]({{my_macro}}src/02-common-principles.md#units)
• In the sessions-file section, there is a schema call to insert the acq_time schema description, so [Units]({{my_macro}}src/02-common-principles.md#units) will be pasted there
• In the next round of macro evaluations, the macro caller will find [Units]({{my_macro}}/02-common-principles.md#units) and work on it, replacing it by:
  • [Units](../src/02-common-principles.md#units)
• Finally, Mkdocs will properly render that relative link

This is arguably a bit hacky, because ../src/02-common-principles.md#units is a relative link that first goes up the folder hierarchy, and then down again ... but I think that should work.

You have way more experience with MkDocs macros ... would this work @tsalo?

[tsalo]

My only concern is that external schema users (e.g., the NIDM-Terms team) might have problems with macro-based hyperlinks. @dbkeator would having odd hyperlinks in the schema object descriptions be a problem for the BIDS-Terms effort?

[sappelhoff]

Thinking about this again:

In the current terms, we have something like: [Units](../src/02-common-principles.md#units), which is arguably meaningless without access to ../src/... In my proposal, we would simply change this to [Units]({{my_macro}}src/02-common-principles.md#units) --> this doesn't seem any worse, does it? :-)

[tsalo]

Per today's dev call, we may want to move as many links to things outside the schema into the addendum sections as possible, with the idea being that links in the schema should primarily be to other elements of the schema. And external links, I guess. There's no way to completely drop external links...

That doesn't mean we don't need a solution though.