Markdown support for cross-project links to files
Description
Gitlab-Flavored Markdown (GFM) will let you do cross-project links to everything except files. Being able to do cross-project links to particular files would be useful in particular for writing wiki pages, because a gitlab wiki is technically in a separate repo than the main code repository for its project. That means that currently, if you want to have a wiki page include a link to a file in the code repo, you have to specify it as an absolute link.
Current: [README](https://gitlab.example.com/namespace/project/blob/master/usr/doc/README.md)
Proposed: [README](namespace/project:usr/doc/README.md)
Proposal
Currently GFM uses a separate punctuation mark for each type of Gitlab entity you can convenience-link to:
-
#issue -
!merge request -
%milestone -
$snippet -
@commit -
~issues by label
So it would make sense to add another punctuation mark to indicate a cross-project file link. It can't be _ or . or - because those can be in project names. Perhaps : would be good?
Links / references
Current GFM link syntax: https://docs.gitlab.com/ce/user/markdown.html#special-gitlab-references
Documentation blurb
(Adding the documentation for this to the bottom of the current GFM links table.)
GFM also recognizes certain cross-project references:
| input | references |
|---|---|
namespace/project#123 |
issue |
namespace/project!123 |
merge request |
namespace/project%123 |
milestone |
namespace/project$123 |
snippet |
namespace/project@9ba12248 |
specific commit |
namespace/project@9ba12248...b19a04f5 |
commit range comparison |
namespace/project~"Some label" |
issues with given label |
namespace/project:doc/README |
repository file references |
namespace/project:doc/README#L13 |
repository file line references |
It also has a shorthand version to reference other projects from the same namespace:
| input | references |
|---|---|
project#123 |
issue |
project!123 |
merge request |
project%123 |
milestone |
project$123 |
snippet |
project@9ba12248 |
specific commit |
project@9ba12248...b19a04f5 |
commit range comparison |
project~"Some label" |
issues with given label |
project:doc/README |
repository file references |
project:doc/README#L13 |
repository file line references |