- Issue created by @fjgarlin
- 🇪🇸Spain fjgarlin
Navigation might be real tricky.
Take as example these two files from core:
- README.md
- composer/Plugin/Scaffold/README.mdWe could view these files:
1. Locally loading from the text editor ("drupal" is in the root folder)
2. Locally loading from the text editor ("drupal" is in the root/web folder)
3. Via git.drupalcode.org from "drupal" root page: https://git.drupalcode.org/project/drupal/-/blob/11.x
4. Via git.drupalcode.org from the "md" file page: https://git.drupalcode.org/project/drupal/-/blob/11.x/README.mdIf we set the link from the first file to the second like:
- "/composer/Plugin/Scaffold/README.md" (1 ✅, 2 ❌, 3 ❌, 4 ❌)
- "composer/Plugin/Scaffold/README.md" (1 ❌, 2 ✅, 3 ❌, 4 ✅,)If we set the link from the second file to the first like:
- "/README.md" (1 ✅, 2 ❌, 3 ❌, 4 ❌)
- "../../../README.md" (1 ❌, 2 ✅, 3 ❌, 4 ✅,)The first syntax is the ideal and most simple, but it only works locally when drupal core is the root folder. This will not work if trying to jump between MD files in GitLab or Github.
So, the only alternative might actually be to provide what the api.drupal.org will be (eg: https://api.drupal.org/api/drupal/README.md, and this issue will be used to add the branch suffix "/11.x"). This will make navigation from 1, 2, 3, 4 jump to the api.drupal.org site, but it will always work.
- 🇪🇸Spain fjgarlin
Per slack thread with core maintainers https://drupal.slack.com/archives/C03P8AM3B0Q/p1752594002161159 (private channel).
We will write links in the MD files as
[link to readme](https://api.drupal.org/api/drupal/README.md)and then:
- When navigating, it will assume the latest/default branch if no branch suffix is present
- When rendering the file, the correct branch suffix will be added to the rendered file, so that navigation in non-default branches is still possible.Positive votes: @catch, @nod_, @longdave, @quietone