Document that workspace crates should use absolute image URLs in README
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 15.5k
- Forks
- 3k
- Avg merge
- 23h 30m
- Merged PRs (30d)
- 51
Description
When a workspace crate references a root-level README via a relative path (e.g. readme = "../../README.md"), any relative image URLs in that README will not resolve correctly on crates.io. This is because crates.io resolves paths relative to the crate subdirectory, not the repository root.
The workaround is to use absolute URLs (e.g. https://raw.githubusercontent.com/{owner}/{repo}/HEAD/path/to/image.png), but this is not documented anywhere obvious. It's only discoverable by digging through closed issue comments:
- https://github.com/rust-lang/crates.io/issues/9939
- https://github.com/rust-lang/crates.io/issues/9886
- https://github.com/rust-lang/crates.io/issues/13376 (redirected here)
It would help to add a note to the package.readme section of the Cargo reference, e.g.:
Note: If your crate lives in a subdirectory and references a README outside the crate directory (e.g.
readme = "../../README.md"), relative image URLs in that README will not resolve correctly on crates.io. Use absolute URLs for images instead.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the Cargo reference's package.readme section, linked in the issue, and review how README paths are currently documented. Add a note explaining the workspace-crate case and recommending absolute image URLs, then verify that the reference clearly covers the example and crates.io behavior described in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100