Show HN: Rustdoc-style linking in mdBook (with the help of Rust-analyzer)

1 points by tonywu6_ 9 days ago

[rustdoc], Rust's API documentation generator, supports linking to Rust APIs by names, which is great DX because you don't have to hard-code URLs in docs, and it guarantees the links are correct. The same feature can be found in Javadoc, Go Doc, etc.

[mdBook] is another documentation/static-site generator written in Rust and widely used in the Rust community. It generates sites from Markdown (so like Docusaurus, VitePress, etc.)

Unlike rustdoc, mdBook doesn't have the same "linking by name" capability, which I find a bit lacking — so I made this program!

mdbook-rustdoc-link is an mdBook preprocessor that you can plug into your book projects. Using [rust-analyzer], it converts Rust API names to docs.rs permalinks, just like rustdoc does. It can link to APIs in your own crate and in your dependencies, without you having to manually search for and copy and paste URLs into your Markdown pages.

[rustdoc]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html

[mdBook]: https://rust-lang.github.io/mdBook/

[rust-analyzer]: https://rust-analyzer.github.io/