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.
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.readmesection of the Cargo reference, e.g.: