Wrong link to image in markdown

[Lorak-mmk]

Current Behavior

In our README.md file we have an image:

<img src="assets/monster+rust.png" height="150" align="right">

Link to this line: https://github.com/scylladb/scylla-rust-driver/blob/f59908c54e6b6407112311a3745e32d4bd218d0c/README.md?plain=1#L1
It has not been edited for 4 years. The image is located at https://github.com/scylladb/scylla-rust-driver/blob/main/assets/monster%2Brust.png - again, in the same place for 4 years now.

Today we released new version of the crate, and the page on crates.io no longer shows the image: https://crates.io/crates/scylla/0.15.0

This is because it links to https://github.com/scylladb/scylla-rust-driver/raw/HEAD/scylla/assets/monster+rust.png - notice the additional /scylla in the URL after /HEAD

All previous releases were working correctly - most recent one in September (so it is relatively recently introduced bug): https://crates.io/crates/scylla/0.14.0

In this release link leads to https://github.com/scylladb/scylla-rust-driver/raw/HEAD/assets/monster+rust.png - no more /scylla after /HEAD.

Expected Behavior

I expected the image to be correctly displayed, as it always was.

Steps To Reproduce

1. Go to: https://crates.io/crates/scylla/0.14.0
2. Image works
3. Go to https://crates.io/crates/scylla/0.15.0
4. Image doesn't work despite the markdown source being the same

Environment

Not sure it is relevant here, but I'll include it anyway.

• Browser: Firefox 130
• OS: Fedora 39

I also verified this on Chromium

Anything else?

No response

[Lorak-mmk]

Oh, I see that there was already #9886
And we do use readme = "../README.md"
But this issue basically says "this is how cargo works, sorry" - while it did work correctly 2 months ago, so it still looks like a regression.

[Turbo87]

it did work correctly 2 months ago

huh, that's interesting. I don't remember any changes that would've caused this, but I'll take a closer look tomorrow.

it still looks like a regression.

I guess that depends on the viewpoint. My assumption is that 2 months ago we might not have taken https://docs.rs/crate/scylla/0.14.0/source/.cargo_vcs_info.json#5 into account yet (?). In your case this might look like a regression, but for people with README.md files that are actually in nested folders and don't rely on the cargo magic this would have fixed their relative paths.

[Lorak-mmk]

it did work correctly 2 months ago

huh, that's interesting. I don't remember any changes that would've caused this, but I'll take a closer look tomorrow.

it still looks like a regression.

I guess that depends on the viewpoint. My assumption is that 2 months ago we might not have taken https://docs.rs/crate/scylla/0.14.0/source/.cargo_vcs_info.json#5 into account yet (?). In your case this might look like a regression, but for people with README.md files that are actually in nested folders and don't rely on the cargo magic this would have fixed their relative paths.

What is the correct / recommended way to use relative image link in our situation?

[epage]

Linking out to any potential cargo-related changes:

• Better support for license-file. cargo#7905 (Cargo 1.43) added support for copying package.license-file into the package root on cargo package.
• Part 4 of RFC2906 - Add support for inheriting readme cargo#10548 (Cargo 1.62) did the same for package.readme
• Include vcs_info even if workspace is dirty cargo#13960 (Cargo 1.81) changed cargo package to include .cargo_vcs_info.json even when --allow-dirty is used. However, looking through old versions of scylla, I'm always seeing .cargo_vcs_info.json so this is unlikely to have made a difference.

Besides moving of files, there are also symlinks. cargo package reads the target for symlinks and includes them in the .crate file. This means that if your package.readme = "README.md" is actually for a symlink to ../README.md or foo/bar/README.md, Cargo will write the content to README.md and the links could also be off

Potential options on cargo's side

• Include in .cargo_vcs_info.json any file remapping we do, explicitly and through symlinks

[kornelski]

For authors, I recommend using absolute image URLs in the README.

The relative URLs in README are a fiction with no basis in any web standard. Making these URLs work as expected relies on reverse-engineering custom URL schemes of 3rd party services.

The rewriting of the URLs is full of annoying edge cases due to symlinks, ../README paths, location of the crate within repo (which can be different than the location of the README), and the need to normalize .. in URLs in multiple different ways, also in a way that is host-specific. The assets may exist only at a specific commit or branch the crate has been published from, but Cargo doesn't always have this information.

[Lorak-mmk]

We'll change the url to the absolute one.
It is a bit sad that relative urls don't work well, because now the link in README doesn't refer to the file in the repo in the same commit, but to the outside file that just happens to be the same because we don't change the logo.

Btw is there a way for us to test crates.io rendering without releasing a new version of the crate?