Rust crate maintainers warned about broken README links on crates.io

Relative links in crate READMEs can break the moment a package lands on crates.io, leaving a polished repository page with missing license links, broken logos, or dead example references. The common culprits are direct: a LICENSE file linked as ./LICENSE and an embedded logo pointed at ../../assets/logo.png.

The problem is packaging context. In a Git repository, README links are interpreted against the tree you are browsing, so a relative path often works exactly as intended. Once the crate is published, that context disappears. crates.io ships crates as tar.gz files, not as a live repository with URLs for every file, so the same README can render with gaps when it is shown on the package page or carried through the documentation pipeline.

The practical fix is simple but easy to miss during release prep: use absolute URLs for anything that must survive publication. That includes hosted images, documentation pages, license text, and other assets that a maintainer expects to stay visible after the crate is published. For crates that depend on screenshots, badges, logos, or multi-file legal notices, those links are part of the first impression.

rust-lang/cargo issue #8434 is titled Fixup of repository-relative URLs in READMEs, while issue #16865 is titled Document that workspace crates should use absolute image URLs in README. Another related thread, Relative paths in Cargo.toml readme, tracks the same README path-handling issue.

On 2024-06-28, Daniel McNab published #![doc = include_str!()] with intra-doc links, and the links had to work wherever the README is rendered, including web views. RFC 1946, intra-rustdoc-links, is the earlier Rust reference point for link portability.