You do not need html_root_url

It's somewhat common to have lines like this in crates:

// Cargo.toml
name = "foo"
version = "0.1.2" # Also update html_root_url in when bumping this

#![doc(html_root_url = "")]

For a long time I was quite annoyed by such version duplication. But it turns out that you do not need html_root_url on modern toolchains!

See the following links for more information:


I thought that attribute was made redundant back when they started linking to by default?

Setting html_root_url is still immensely useful when building crate documentation locally. If building with cargo doc --no-deps types are not linked unless the source crate specifies html_root_url.

Possible solutions like -Zrustdoc-map are still unstable. Until then, keeping the attribute still is useful and crates like version-sync ensures that all version numbers are kept in sync. After all, there might be more places with version duplication.


I got tired of forgetting to update the version number so I created a tiny crate called version-sync which will detect if the attribute is out of date.

I've since then also managed to automate my release process so that the attribute is updated by a script. See prepare-release.yml if you're curious.

It would of course be great if the attribute could be deprecated completely.

It would be nice if usage for could be deprecated/made unnecessary, but it still has use for when documentation is special built not on docsrs (say, for exotic platform(s), or closed-source internal registries.)

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.