Codeberg/Community
54
324
Fork
You've already forked Community
12

relative link in Markdown file #252

Open
opened 2020年09月08日 08:50:22 +02:00 by ivan-paleo · 24 comments

I like to link directly to documents in my repos in the README.md.
On GitHub, I can write something like [file](/file.html), but it apparently doesn't work on Codeberg.

Is there any workaround?

Of course, I could specify the whole path, e.g. https://codeberg.org/username/initiationR/src/branch/master/file.html, but that is suboptimal, right?

Sorry for this probably basic question, but the move from GitHub to Codeberg is less smooth than I anticipated :)

upstream: https://github.com/go-gitea/gitea/issues/18592

I like to link directly to documents in my repos in the README.md. On GitHub, I can write something like `[file](/file.html)`, but it apparently doesn't work on Codeberg. Is there any workaround? Of course, I could specify the whole path, e.g. https://codeberg.org/username/initiationR/src/branch/master/file.html, but that is suboptimal, right? Sorry for this probably basic question, but the move from GitHub to Codeberg is less smooth than I anticipated :) --- upstream: https://github.com/go-gitea/gitea/issues/18592

I suspect the problem is the bare leading slash, which usually means "resource at the root of the host".

Try placing a dot before the leading slash or removing the leading slash, so try either [file](./file.html) or [file](file.html).

Sorry for this probably basic question, but the move from GitHub to Codeberg is less smooth than I anticipated :)

No problem, you're welcome to ask questions! :) We're working on making this smoother, for example by providing better documentation.

I suspect the problem is the bare leading slash, which usually means "resource at the root of the host". Try placing a dot before the leading slash or removing the leading slash, so try either `[file](./file.html)` or `[file](file.html)`. > Sorry for this probably basic question, but the move from GitHub to Codeberg is less smooth than I anticipated :) No problem, you're welcome to ask questions! :) We're working on making this smoother, for example by providing better documentation.

Thank you @lhinderberger, both solutions work: [file](./file.html) or [file](file.html)

Thank you @lhinderberger, both solutions work: `[file](./file.html)` or `[file](file.html)`

You're welcome! :)

You're welcome! :)

No problem, you're welcome to ask questions! :) We're working on making this smoother, for example by providing better documentation.

Documentation is lacking a bit indeed, but apparently, the community support is great!

> No problem, you're welcome to ask questions! :) We're working on making this smoother, for example by providing better documentation. Documentation is lacking a bit indeed, but apparently, the community support is great!

We're in the process of collecting documentation resources at https://docs.codeberg.org/ - feel free to have a look or even contribute at https://codeberg.org/Codeberg/Documentation

We're in the process of collecting documentation resources at https://docs.codeberg.org/ - feel free to have a look or even contribute at https://codeberg.org/Codeberg/Documentation

I was indeed starting to wonder how I could contribute, so I will definitely check what I can do there :)

I was indeed starting to wonder how I could contribute, so I will definitely check what I can do there :)

As indicated in Codeberg/Documentation#67, treating URLs in Markdown that start with a slash not as relative to the repository root but as relative to the web root could be worth reconsidering.

We might want to write a PR to gitea to change that behavior?

As indicated in Codeberg/Documentation#67, treating URLs in Markdown that start with a slash not as relative to the repository root but as relative to the web root could be worth reconsidering. We might want to write a PR to gitea to change that behavior?

Since this problem is still a thing, I decided to forward this issue to upstream: https://github.com/go-gitea/gitea/issues/18592

Since this problem is still a thing, I decided to forward this issue to upstream: https://github.com/go-gitea/gitea/issues/18592

GitHub indeed interprets this as referring to the repository root rather than the host, which IMHO is also the only way that makes sense. The problem is that all other ways of linking across complex documentation will break the links if you move the source file around where the link comes from (which is I think for most people a super unexpected breakage), not just the target file being moved around (which would be expected to break links).

As a result, there isn't really an alternative to these types of links for complex nested documentation.

So this is IMHO a quite high impact bug for projects with complex markdown documentation, and it would be very nice to see this fixed. In my own project's documentation, almost all links are broken in the documentation due to this while they work fine on the GitHub mirror, which doesn't shed the best light on Codeberg for the average unsuspecting user just wanting to browse the documentation.

GitHub indeed interprets this as referring to the repository root rather than the host, which IMHO is also the only way that makes sense. The problem is that all other ways of linking across complex documentation will break the links if you move the *source* file around where the link comes from (which is I think for most people a super unexpected breakage), not just the *target* file being moved around (which would be expected to break links). As a result, there isn't really an alternative to these types of links for complex nested documentation. So this is IMHO a quite high impact bug for projects with complex markdown documentation, and it would be very nice to see this fixed. In my own project's documentation, **almost all links are broken** in the documentation due to this while they work fine on the GitHub mirror, which doesn't shed the best light on Codeberg for the average unsuspecting user just wanting to browse the documentation.
Owner
Copy link

Well, if you want to link to another project, no matter on which instance you are on, this makes a lot of sense:

Assume your organization is called X and you want X/y to link to X/z on Codeberg, Disroot and many other instances. It makes sense to put /X/z there, relative to the host.

It is basically the default for the web. Adding the behaviour GitHub introduces might introduce unexpected behaviour for everyone who is expecting Codeberg to work like every other website.

If you want links relative to your project, use relative links. They'll also work if you open the files in your local editor (if they support links), because it's very unlikely that you want to link to /something on your computer instead of something relative to your file.

This is not a bug. You can enhance it, maybe you can add a javascript prompt which link to open, or autodetect it or whatever. But simply changing the behaviour is not an option IMHO. Absolute links will always break if you switch the context. As easy as that.

Well, if you want to link to another project, no matter on which instance you are on, this makes a lot of sense: Assume your organization is called X and you want X/y to link to X/z on Codeberg, Disroot and many other instances. It makes sense to put /X/z there, relative to the host. It is basically the default for the web. Adding the behaviour GitHub introduces might introduce unexpected behaviour for everyone who is expecting Codeberg to work like every other website. If you want links relative to your project, use relative links. They'll also work if you open the files in your local editor (if they support links), because it's very unlikely that you want to link to /something on your computer instead of something relative to your file. This is not a bug. You can enhance it, maybe you can add a javascript prompt which link to open, or autodetect it or whatever. But simply changing the behaviour is not an option IMHO. Absolute links will always break if you switch the context. As easy as that.

Maybe I just don't get it, but this leaves me baffled: I personally don't think this makes much sense, wouldn't you always specify a project with the full VCS host anyway?

It seems a considerably more arcane use case to me than wanting to link into another folder in the same project without having to fix the links in way more locations if you ever dare move something around. Basically, to me your proposed use case makes only sense in the very obscure scenario that 1. I want to link a target on the same VCS host, 2. I want the link target to be another repo and another org and I don't want to just use /../../ (which would be the natural way to specify that with the github interpretation of relative to the project root), 3. and for some reason I really don't want to specify it fully with VCS host like everyone usually would for inter-project dependencies anyway, 4. and I'm maybe planning to rename my entire VCS host quite regularly and somehow want to optimize for that, or somehow move VCS hosts with all my projects in the future while assuming all the same paths and org names are free and somehow not wanting to adjust all that.

I don't know, that doesn't seem like a rather realistic use case to me. On the other hand, just linking between two docs folders and I don't want to adjust both sides if I dare move a file around seems like a very common use case.

Edit: maybe there's the special scenario that I own both the VCS host and the domain it runs on, but this isn't the case for 99% of codeberg users. It might be if you self-host gitea or forgejo, but maybe then it should be at least a setting so for Codeberg it can be set to something that works better for all the users. But even then, if almost all VCS hosts interpret the / paths project-relative at the end of the day, would you really want a setting to deviate anyway? I don't fully follow.

Maybe I just don't get it, but this leaves me baffled: I personally don't think this makes much sense, wouldn't you always specify a project with the full VCS host anyway? It seems a considerably more arcane use case to me than wanting to link into another folder in the same project without having to fix the links in way more locations if you ever dare move something around. Basically, to me your proposed use case makes only sense in the very obscure scenario that 1. I want to link a target on the same VCS host, 2. I want the link target to be *another* repo **and** another org **and** I don't want to just use `/../../` (which would be the natural way to specify that with the github interpretation of relative to the project root), 3. and for some reason I really don't want to specify it fully with VCS host like everyone usually would for inter-project dependencies anyway, 4. and I'm maybe planning to rename my entire VCS host quite regularly and somehow want to optimize for that, or somehow move VCS hosts with all my projects in the future while assuming all the same paths and org names are free and somehow not wanting to adjust all that. I don't know, that doesn't seem like a rather realistic use case to me. On the other hand, just linking between two docs folders and I don't want to adjust *both* sides if I dare move a file around seems like a very common use case. Edit: maybe there's the special scenario that I own both the VCS host and the domain it runs on, but this isn't the case for 99% of codeberg users. It might be if you self-host gitea or forgejo, but maybe then it should be at least a setting so for Codeberg it can be set to something that works better for all the users. But even then, if almost all VCS hosts interpret the `/` paths project-relative at the end of the day, would you really want a setting to deviate anyway? I don't fully follow.

For what it's worth, it looks like upstream is about to merge a fix to achieve the behavior I just advocated for and which this issue is suggesting. So if anyone here wanted to oppose that, now would probably be the time (not that I personally would think that it should be opposed, just letting y'all know how things seem to be developing).

For what it's worth, it looks like upstream is about to merge a fix to achieve the behavior I just advocated for and which this issue is suggesting. So if anyone here wanted to oppose that, now would probably be the time (not that I personally would think that it should be opposed, just letting y'all know how things seem to be developing).

I would personally think that the only party that benefits from this sort of behavior is, well, just Codeberg. We tend to go along with the upstream's decisions.

Huge thanks for letting us know about that, but, to me, that's probably not a proper hill to die on.

I would personally think that the only party that benefits from this sort of behavior is, well, just Codeberg. We tend to go along with the upstream's decisions. Huge thanks for letting us know about that, but, to me, that's probably not a proper hill to die on.

A small update: while https://github.com/go-gitea/gitea/issues/18592 was filed and at least to me some comments from the developers made it sound like a fix was intended, so far this isn't working in gitea yet and neither is it working in forgejo. The issue is also still marked as open in the upstream repository, as you can see.

Edit: seems like maybe there was confusion about the situation and nothing was decided after all. So I guess if anyone wants to weigh in on upstream gitea how this should be handled, now might be useful.

A small update: while https://github.com/go-gitea/gitea/issues/18592 was filed and at least to me some comments from the developers made it sound like a fix was intended, so far this isn't working in gitea yet and neither is it working in forgejo. The issue is also still marked as open in the upstream repository, as you can see. Edit: seems like maybe there was confusion about the situation and nothing was decided after all. So I guess if anyone wants to weigh in on upstream gitea how this should be handled, now might be useful.

This was just fixed in Gitea https://github.com/go-gitea/gitea/issues/18592

The correct behavior is to allow these project-relative links to work. And I think they used to work recently enough and something broke them. I urge that a solution be found ASAP, ideally just pulling in whatever that Gitea fix is (perhaps to Forgejo and then to Codeberg)

This was just fixed in Gitea https://github.com/go-gitea/gitea/issues/18592 The correct behavior is to allow these project-relative links to work. And I think they used to work recently enough and something broke them. I urge that a solution be found ASAP, ideally just pulling in whatever that Gitea fix is (perhaps to Forgejo and then to Codeberg)

For what it's worth, it seems like Gitea now has implemented both abc/def/other_file.md links relative to the current file, and /abc/def/other_file.md links relative to the repository root. Both these variants work on GitHub as well.

For what it's worth, it seems like Gitea now has implemented both `abc/def/other_file.md` links relative to the current file, and `/abc/def/other_file.md` links relative to the repository root. Both these variants work on GitHub as well.

yes, but /abc/def/other_file.md is not working at Codeberg right now! So, we need that bug fixed ASAP

yes, but /abc/def/other_file.md is *not* working at Codeberg right now! So, we need that bug fixed ASAP

I really need to know whether this is going to get fixed or whether I need to do the workarounds to precisely mark every link within a repo.

I imagine this is simple enough to just use the Gitea fix in this case

I really need to know whether this is going to get fixed or whether I need to do the workarounds to precisely mark every link within a repo. I imagine this is simple enough to just use the Gitea fix in this case

Please note I'm not a codeberg contributor, but if I wanted to know badly I would clone forgejo, then simply try to apply the Gitea fix, and then test locally if the fix works. If it does, you could link the patch with a confirmation to fast track it or even make a pull request directly. It seems otherwise it may depend on whenever somebody gets time to look at this which I assume might be a while. Sorry if this isn't a helpful suggestion.

Please note I'm not a codeberg contributor, but if I wanted to know badly I would clone forgejo, then simply try to apply the Gitea fix, and then test locally if the fix works. If it does, you could link the patch with a confirmation to fast track it or even make a pull request directly. It seems otherwise it may depend on whenever somebody gets time to look at this which I assume might be a while. Sorry if this isn't a helpful suggestion.

Thanks, I can at least note here the direct links to two PRs that seem the relevant ones:

https://github.com/go-gitea/gitea/pull/32612 and https://github.com/go-gitea/gitea/pull/32640

and these do a lot of changes that I imagine are easy enough to pull in but not trivial for a first-time contributor to make sense of. I am tempted to try because of how important I think this fix is, but I worry this is much more work for me than for someone set up to do this already.

I think the immediate question is: should this be opened at https://codeberg.org/forgejo/forgejo/issues rather than just living here in Codeberg/Community issues? I think so... what's the protocol there?

Thanks, I can at least note here the direct links to two PRs that seem the relevant ones: https://github.com/go-gitea/gitea/pull/32612 and https://github.com/go-gitea/gitea/pull/32640 and these do a lot of changes that I imagine are easy enough to pull in *but* not trivial for a first-time contributor to make sense of. I am tempted to try because of how important I think this fix is, but I worry this is much more work for me than for someone set up to do this already. I think the immediate question is: should this be opened at https://codeberg.org/forgejo/forgejo/issues rather than just living here in Codeberg/Community issues? I think so... what's the protocol there?

Thanks, I can at least note here the direct links to two PRs that seem the relevant ones:

https://github.com/go-gitea/gitea/pull/32612 and https://github.com/go-gitea/gitea/pull/32640

These are one of a number of refactors in this area in Gitea. The code has diverged substantially.

rather than just living here in Codeberg/Community issues? I think so... what's the protocol there?

The ideal path is to (increasing level of completion / difficulty

  • open (or find an existing) issue
  • create a reproducer on https://dev.next.forgejo.org to confirm it is still in the development branch
  • create or modify a test in the codebase to reproduce the problem
  • add a fix that turns the test from failing to succeeding
  • get it merged
> Thanks, I can at least note here the direct links to two PRs that seem the relevant ones: > > https://github.com/go-gitea/gitea/pull/32612 and https://github.com/go-gitea/gitea/pull/32640 These are one of a number of refactors in this area in Gitea. The code has diverged substantially. > rather than just living here in Codeberg/Community issues? I think so... what's the protocol there? The ideal path is to (increasing level of completion / difficulty * open (or find an existing) issue * create a reproducer on https://dev.next.forgejo.org to confirm it is still in the development branch * create or modify a test in the codebase to reproduce the problem * add a fix that turns the test from failing to succeeding * get it merged

For what it's worth, a reproducer can e.g. also be found here: click "horsec" in the first sentence.

For what it's worth, a reproducer can e.g. also be found here: [click "horsec"](https://codeberg.org/Horse64/core.horse64.org/src/branch/main/docs/Compilation.md) in the first sentence.

Can you help locate which issue exists or make a new one?

Can you help locate which issue exists or make a new one?

I scanned through all the markdown issues and it doesn't seem to have been filed. I filed the problem here now.

I scanned through all the markdown issues and it doesn't seem to have been filed. [I filed the problem here now](https://codeberg.org/forgejo/forgejo/issues/6360).
Sign in to join this conversation.
No Branch/Tag specified
main
No results found.
Labels
Clear labels
accessibility

Reduces accessibility and is thus a "bug" for certain user groups on Codeberg.
bug

Something is not working the way it should. Does not concern outages.
bug
infrastructure
Errors evidently caused by infrastructure malfunctions or outages
Codeberg

This issue involves Codeberg's downstream modifications and settings and/or Codeberg's structures.
contributions welcome

Please join the discussion and consider contributing a PR!
docs

No bug, but an improvement to the docs or UI description will help
duplicate

This issue or pull request already exists
enhancement

New feature
infrastructure

Involves changes to the server setups, use `bug/infrastructure` for infrastructure-related user errors.
legal

An issue directly involving legal compliance
licence / ToS

involving questions about the ToS, especially licencing compliance
please chill
we are volunteers
Please consider editing your posts and remember that there is a human on the other side. We get that you are frustrated, but it's harder for us to help you this way.
public relations

Things related to Codeberg's external communication
question

More information is needed
question
user support
This issue contains a clearly stated problem. However, it is not clear whether we have to fix anything on Codeberg's end, but we're helping them fix it and/or find the cause.
s/Forgejo

Related to Forgejo. Please also check Forgejo's issue tracker.
s/Forgejo/migration

Migration related issues in Forgejo
s/Pages

Issues related to the Codeberg Pages feature
s/Weblate

Issue is related to the Weblate instance at https://translate.codeberg.org
s/Woodpecker

Woodpecker CI related issue
security

involves improvements to the sites security
service

Add a new service to the Codeberg ecosystem (instead of implementing into Gitea)
upstream

An open issue or pull request to an upstream repository to fix this issue (partially or completely) exists (i.e. Gitea, Forgejo, etc.)
wontfix

Codeberg's current set of contributors are not planning to spend time on delegating this issue.
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
8 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Codeberg/Community#252
Reference in a new issue
Codeberg/Community
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?