Relative URLs in subdirectory readmes

[clehner]

During readme markdown rendering, links with relative URLs in a crate's readme are resolved relative to the repository root, even if the crate and its readme file are in a subdirectory of the repository. This breaks consistency with how relative URLs are resolved in the source site - relative to the file in the subdirectory.

An example of a repository with multiple crates in subdirectories (using absolute URLs in the readmes):
https://github.com/RustCrypto/elliptic-curves/

An example of a crate published from a subdirectory using relative URLs in the readme which are rendered broken:
https://crates.io/crates/ssi-contexts/0.0.2
while in the source code they are working:
https://github.com/spruceid/ssi/blob/ssi-contexts%2F/v0.0.2/contexts/README.md

It would be nice if relative URLs could be used in subdirectory readmes. Possible solutions:

1. Resolve relative to the homepage property rather than the repository property.
2. Add a readme_url metadata field, to use as the base URL for resolution.
3. Add a repository_path metadata field that would be the path of the crate in the repository - where the readme is assumed to reside - for use in evaluating relative URLs in the readme.

[nipunn1313]

@rustbot claim

I started looking at this. Unfortunately, as @clehner determined, it seems that crates.io doesn't have enough information at time of render to determine the subdirectory that the README is in.

relevant code:

crates.io/src/controllers/krate/publish.rs

Line 189 in d04dc22

render::render_and_upload_readme(

and relevant code where "readme_file" is determined in cargo
https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/registry.rs#L284

Resolve relative to the homepage property rather than the repository property.

Not sure this helps here - as the homepage isn't necessarily on github/etc showing code.

Add a readme_url metadata field, to use as the base URL for resolution.

This definitely doesn't seem like something we'd want to expose as something to fill in the Cargo.toml. Seems that cargo should be able to infer it. Perhaps it could be inferred by cargo and added here. Still seems like if it's possible to do this with less complexity, we should see if we can.
https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/registry.rs#L284

Add a repository_path metadata field that would be the path of the crate in the repository - where the readme is assumed to reside - for use in evaluating relative URLs in the readme.

Again - something we could have cargo infer and send on the network to crates.io

Proposal:

crates.io already gets the readme_file which it interprets as a filename in order to use the extension. It is actually passed the relative path to the README from the pkg root (from the Cargo.toml) here

• Update crates.io to use the readme filename's directory in the relative URL generated here. Essentially generate "{repo}/blob/HEAD/{relative_path_to_readme}/{relative_url}"

This would handle readmes not in root (eg docs/README.md), but only if the Cargo.toml was in the repo root

As a bonus, if we want to handle Cargo.toml that aren't in the repo root, we can

• Update cargo to give the relative path to the README from the REPO root rather than pkg root. AFAICT, crates.io only uses the readme path (currently) for the extension - to decide how to render.

[nipunn1313]

Update crates.io to use the readme filename's directory in the relative URL generated here. Essentially generate "{repo}/blob/HEAD/{relative_path_to_readme}/{relative_url}"

I took a stab at this in #3861

[nipunn1313]

As a bonus, if we want to handle Cargo.toml that aren't in the repo root, we can

Update cargo to give the relative path to the README from the REPO root rather than pkg root. AFAICT, crates.io only uses the readme path (currently) for the extension - to decide how to render.

Also took a stab at this in
rust-lang/cargo#9837