rust-lang / rust-lang/cargo

Document that workspace crates should use absolute image URLs in README

Open Beginner friendly
#16,865 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-documenting-cargo-itself C-enhancement
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:

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.