Motivation
rustdoc supports linking to items by name, a.k.a. intra-doc links. This is awesome for at least two reasons:
- It's convenient. It could be as simple as just adding brackets.
- Docs.rs will generate cross-crate links that are version-pinned.
mdBook doesn't have the luxury of accessing compiler internals yet, so you are left with manually sourcing links from docs.rs. Then one of two things could happen:
-
APIs are mentioned without linking to reference docs.
This is probably fine for tutorials and examples, but it does mean readers of your docs won't be able to move from guides to references as easily.
-
You do want at least some cross-references, but it is cumbersome to find and copy the correct links, and even more so to maintain them.
Links to docs.rs often use
latestas the version, which could become out-of-sync with your code, especially if they point to third-party or unstable APIs.
mdbook-rustdoc-link is the tooling answer to these problems. Effortless, correct, and
good practice — choose all three!
note
That being said, sometimes manually specifying URLs is the best option.
Most importantly, writing links by name means they won't be rendered as such when your Markdown source is displayed elsewhere. If your document is also intended for places like GitHub or crates.io, then you should probably not use this preprocessor.