[GH-ISSUE #735] Broken Links on Docs #1369

New issue

Closed

opened 2026-03-14 14:33:44 +03:00 by kerem · 2 comments

kerem commented

2026-03-14 14:33:44 +03:00

Owner

Originally created by @brianmego on GitHub (May 28, 2025).
Original GitHub issue: https://github.com/aome510/spotify-player/issues/735

in crates.io (and lib.rs) several links in the README.md are broken.

"Highly configurable"
"examples/README.md"
"configuration documentation"
"general configuration file"

The links all resolve here in the github rendering of the README, so I'm assuming it's something to do with whatever build script you have to submit it up to crates.io or your local build system.

Originally created by @brianmego on GitHub (May 28, 2025). Original GitHub issue: https://github.com/aome510/spotify-player/issues/735 in crates.io (and lib.rs) several links in the README.md are broken. "Highly configurable" "examples/README.md" "configuration documentation" "general configuration file" The links all resolve here in the github rendering of the README, so I'm assuming it's something to do with whatever build script you have to submit it up to crates.io or your local build system.

kerem

2026-03-14 14:33:44 +03:00

closed this issue
added the
bug

good first issue
labels

kerem commented

2026-03-14 14:34:00 +03:00

Author

Owner

@KUHLwasStolen commented on GitHub (Jul 29, 2025):

All of the broken links are ones that point to files in this repository (i.e. relative links) and when accessing them via crates.io they all resolve to the following pattern:

https://github.com/aome510/spotify-player/blob/HEAD/spotify_player/ [correct relative path]

Basically when publishing this extra spotify_player is added, without it the links work as intended.
~~I assume it is added because the publish script publishes from the spotify_player directory:~~

crate="${1:-spotify_player}"
...
cd $crate && cargo publish

And because of this relative links are interpreted relative to this current directory, which causes the incorrect insertion of spotify_player when translating to absolute links.

To resolve this I see two options:

Change relative links to absolute links pointing directly to the GitHub repo (which would make local viewing worse and generally make editing the README more complicated)
~~Refactor the publishing process to be executed from the repo root~~

Let me know which option is preferred (or another option that I didn't see) and I can handle/help with the adaptation.

Edit: I might have misunderstood the crate="${1:-spotify_player}" line, which does not necessarily result in "spotify_player" when provided with a command line argument. Sorry.
The issue still seems related to this line though.

Edit 2: I think my previous theory is wrong now. I think the problem is rather caused by readme = "../README.md" in ./spotify_player/Cargo.toml.
Something in the link translation process might not like that the README for that crate is not in the same directory(?)
This is also just a guess, but my most plausible theory at the moment.

@KUHLwasStolen commented on GitHub (Jul 29, 2025): All of the broken links are ones that point to files in this repository (i.e. relative links) and when accessing them via crates.io they all resolve to the following pattern: https://github.com/aome510/spotify-player/blob/HEAD/spotify_player/ [correct relative path] Basically when publishing this extra **spotify_player** is added, without it the links work as intended. ~I assume it is added because the `publish` script publishes from the `spotify_player` directory:~ ```shell crate="${1:-spotify_player}" ... cd $crate && cargo publish ``` And because of this relative links are interpreted relative to this current directory, which causes the incorrect insertion of `spotify_player` when translating to absolute links. To resolve this I see two options: 1. Change relative links to absolute links pointing directly to the GitHub repo (which would make local viewing worse and generally make editing the README more complicated) 2. ~Refactor the publishing process to be executed from the repo root~ Let me know which option is preferred (or another option that I didn't see) and I can handle/help with the adaptation. **Edit:** I might have misunderstood the `crate="${1:-spotify_player}"` line, which does not necessarily result in "spotify_player" when provided with a command line argument. Sorry. The issue still seems related to this line though. **Edit 2:** I think my previous theory is wrong now. I think the problem is rather caused by `readme = "../README.md"` in `./spotify_player/Cargo.toml`. Something in the link translation process might not like that the README for that crate is not in the same directory(?) This is also just a guess, but my most plausible theory at the moment.

kerem commented

2026-03-14 14:34:05 +03:00

Author

Owner

@KUHLwasStolen commented on GitHub (Jul 29, 2025):

I think this is pretty much exactly the same situation: https://github.com/rust-lang/crates.io/issues/9939

To fix the image they used an absolute link and their (relative) link to the example directory does not work.

@KUHLwasStolen commented on GitHub (Jul 29, 2025): I think this is pretty much exactly the same situation: https://github.com/rust-lang/crates.io/issues/9939 To fix the image they used an absolute link and their (relative) link to the example directory does not work.