Known issues

Performance

mdbook-rustdoc-link itself doesn't need much processing power, but it invokes rust-analyzer, which does a full scan of your workspace. The larger your codebase is, the longer mdbook will have to wait for the preprocessor. This is the source of the majority of the run time.

There is an experimental caching feature, which persists query results after runs and reuses them when possible, avoiding spawning rust-analyzer when your edit doesn't involve item links.

Incorrect links

In limited circumstances, the preprocessor generates links that are incorrect or inaccessible.

Macros

Macros exported with #[macro_export] are always exported at crate root, and are documented as such by rustdoc, but rust-analyzer currently generates links to the modules they are defined in. For example:

• panic!, and many other std macros
  • The correct link is https://doc.rust-lang.org/stable/std/macros/macro.panic.html
• serde_json::json!
  • The correct link is https://docs.rs/serde_json/1.0.140/serde_json/macros/macro.json.html

Attribute macros generate links that use macro.<macro_name>.html, but rustdoc actually generates attr.<macro_name>.html. For example:

• tokio::main!
  • The correct link is https://docs.rs/tokio-macros/2.5.0/tokio_macros/macroattr.main.html

Trait items

Rust allows methods to have the same name if they are from different traits, and types can implement the same trait multiple times if the trait is generic. All such methods will appear on the same page for the type.

rustdoc will number the generated URL fragments so that they remain unique within the HTML document. rust-analyzer does not yet have the ability to do so.

For example, these are the same links:

• <std::net::IpAddr as From<std::net::Ipv4Addr>>::from
• <std::net::IpAddr as From<std::net::Ipv6Addr>>::from

The correct link for the From<Ipv6Addr> implementation is actually https://doc.rust-lang.org/stable/core/net/enum.IpAddr.html#method.from-1

Private items

rustdoc has a private_intra_doc_links lint that warns you when your public documentation tries to link to private items.

The preprocessor does not yet warn you about links to private items: rust-analyzer will generate links for items regardless of their crate-level visibility.

Unresolved items

Associated items on primitive types

Links to associated methods and items on primitive types are currently not resolved by rust-analyzer. For example:

• [str::parse]
• [f64::MIN_POSITIVE]

Sites other than docs.rs

Currently, items from crates other than std always generate links that point to https://docs.rs. mdbook-rustdoc-link does not yet support configuring alternative hosting sites for crates (such as wasm-bindgen which hosts API docs under https://rustwasm.github.io/wasm-bindgen/api/).

Wrong line numbers in diagnostics

When the preprocessor fails to resolve some items, it emits warnings that look like:

You may notice that the line numbers are sometimes incorrect for your source file. This could happen in files that use the {{#include}} directive, for example.

This is an unfortunate limitation with mdBook's preprocessor architecture. Preprocessors are run sequentially, with the next preprocessor receiving Markdown source rendered by the previous one. If preprocessors running before mdbook-rustdoc-link modify Markdown source in such ways that shift lines around, then the line numbers will look incorrect.

Unless mdBook somehow gains source map support, this problem is unlikely to ever be solved.