mdbook-rustdoc-links
For best results, view this page at https://docs.tonywu.dev/mdbookkit/rustdoc-links.
Documenting your Rust project using mdBook? Link to your API docs à la rustdoc!
Rustdoc is capable of directly linking to other rustdoc pages using the path of the item as a link. This is referred to as an "intra-doc link".
This preprocessor brings such intra-doc links to mdBook. With it, you can effortlessly add hyperlinks from your book to documentation hosted on docs.rs, as well as to Rust's Standard Library documentation.
Instead of finding and pasting URLs into your book, which can be tedious and error-prone:
The [`option`](https://doc.rust-lang.org/stable/std/option/index.html) and
[`result`](https://doc.rust-lang.org/stable/std/result/index.html) modules define
optional and error-handling types ...
You simply mention items by name, as if writing doc comments ...
The [`option`][std::option] and [`result`][std::result] modules define optional and
error-handling types, [`Option<T>`] and [`Result<T, E>`]. The [`iter`][std::iter] module
defines Rust's iterator trait, [`Iterator`], which works with the `for` loop to access
collections. [^1]
... and you will get:
The option and result modules define optional and
error-handling types, Option<T> and Result<T, E>. The iter module
defines Rust's iterator trait, Iterator, which works with the for loop to access
collections. [^1]
Should you want to refactor your code, the preprocessor also checks your links, so you can keep them up-to-date.
.fg { fill: #B2B2B2 } .bg { fill: #1A1A1A } .fg-bright-blue { fill: #5CADF1 } .fg-yellow { fill: #D19A66 } .container { padding: 0 10px; line-height: 18px; } .bold { font-weight: bold; } tspan { font: 14px Menlo, Roboto Mono, Ubuntu Mono, Liberation Mono, Consolas, ui-monospace, monospace; white-space: pre; line-height: 18px; } warning: unresolved link to `shlex::quote` ╭▸ index.md:1:15 │ 1 │ The [`quote`][shlex::quote] function is deprecated and will be removed soon! ╰╴ ━━━━━━━━━━━━ no item named `quote` in module `shlex` WARN mdbook-rustdoc-links: finished with warnings
Overview
Follow the quickstart tutorial to try out the preprocessor!
For writing documentation,
-
Learn how to write links when using this preprocessor.
-
Learn how to refer to Rust items by name in links so that the preprocessor can resolve them.
See how to configure the preprocessor for specific scenarios, such as:
-
How to link to items in dependencies
-
How to link to conditionally-compiled items
Finally, you can check out the list of all available configuration options.
Happy linking!
[!TIP]
This preprocessor does not require a nightly compiler to function.
License
This project is released under the Apache 2.0 License and the MIT License.
[^1]: Text adapted from A Tour of The Rust Standard Library