# mdbook-rustdoc-links
<div class="hidden">
**For best results, view this page at
[https://docs.tonywu.dev/mdbookkit/rustdoc-links](https://docs.tonywu.dev/mdbookkit/rustdoc-links/index).**
</div>
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_][intra-doc-link] to mdBook. With it,
you can effortlessly add hyperlinks from your book to documentation hosted on
[docs.rs](https://docs.rs), as well as to Rust's
[Standard Library documentation](https://doc.rust-lang.org/stable/std).
Instead of finding and pasting URLs into your book, which can be tedious and
error-prone:
```md
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 ...
```md
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:
<figure class="fig-text">
The [`option`](https://doc.rust-lang.org/1.97.1/core/option/index.html "mod core::option") and [`result`](https://doc.rust-lang.org/1.97.1/core/result/index.html "mod core::result") modules define optional and
error-handling types, [`Option<T>`](https://doc.rust-lang.org/1.97.1/core/option/enum.Option.html "enum core::option::Option") and [`Result<T, E>`](https://doc.rust-lang.org/1.97.1/core/result/enum.Result.html "enum core::result::Result"). The [`iter`](https://doc.rust-lang.org/1.97.1/core/iter/index.html "mod core::iter") module
defines Rust's iterator trait, [`Iterator`](https://doc.rust-lang.org/1.97.1/core/iter/traits/iterator/trait.Iterator.html "trait core::iter::traits::iterator::Iterator"), which works with the `for` loop to access
collections. [^1]
</figure>
Should you want to refactor your code, the preprocessor also checks your links, so you
can keep them up-to-date.
<figure>
<img src="https://github.com/tonywu6/mdbookkit/raw/9fee25e50b174d4a456cad976f744198498d53ff/crates/mdbook-rustdoc-links/tests/book_homepage/stderr/data.svg">
</figure>
## Overview
Follow the [quickstart tutorial](https://docs.tonywu.dev/mdbookkit/rustdoc-links/getting-started) to try out the preprocessor!
For **writing documentation,**
- Learn how to [write links](https://docs.tonywu.dev/mdbookkit/rustdoc-links/writing-links) when using this preprocessor.
- Learn how to [refer to Rust items by name](https://docs.tonywu.dev/mdbookkit/rustdoc-links/naming-items) 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](https://docs.tonywu.dev/mdbookkit/rustdoc-links/how-to/package-selection)
- How to link to [conditionally-compiled items](https://docs.tonywu.dev/mdbookkit/rustdoc-links/how-to/conditional-compilation)
- How to [use the preprocessor in CI/CD](https://docs.tonywu.dev/mdbookkit/rustdoc-links/how-to/continuous-integration)
Finally, you can check out the list of
[all available configuration options](https://docs.tonywu.dev/mdbookkit/rustdoc-links/reference/configuration).
Happy linking!
> [!TIP]
>
> This preprocessor does _not_ require a nightly compiler to function.
## License
This project is released under the [Apache 2.0 License](https://github.com/tonywu6/mdbookkit/tree/9fee25e50b174d4a456cad976f744198498d53ff/LICENSE-APACHE.md) and the
[MIT License](https://github.com/tonywu6/mdbookkit/tree/9fee25e50b174d4a456cad976f744198498d53ff/LICENSE-MIT.md).
[mdBook]: https://rust-lang.github.io/mdBook/
[preprocessor]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html
[intra-doc-link]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html
[tour]: https://doc.rust-lang.org/stable/std/#a-tour-of-the-rust-standard-library