toolkit for mdBook [mirror of my GitHub repo]
docs.tonywu.dev/mdbookkit/
permalinks
rust-analyzer
mdbook
docs: update docs (WIP)
+84
-88
+17
-17
docs/src/SUMMARY.md
+17
-17
docs/src/SUMMARY.md
···
4
4
5
5
---
6
6
7
-
- [rustdoc-link](rustdoc-link/index.md)
8
-
- [Getting started](rustdoc-link/getting-started.md)
9
-
- [Motivation](rustdoc-link/motivation.md)
10
-
- [Name resolution](rustdoc-link/name-resolution.md)
11
-
- [Supported syntax](rustdoc-link/supported-syntax.md)
12
-
- [Workspace layout](rustdoc-link/workspace-layout.md)
13
-
- [Caching](rustdoc-link/caching.md)
14
-
- [Standalone usage](rustdoc-link/standalone-usage.md)
15
-
- [Continuous integration](rustdoc-link/continuous-integration.md)
16
-
- [Configuration](rustdoc-link/configuration.md)
17
-
- [Known issues](rustdoc-link/known-issues.md)
7
+
- [mdbook-rustdoc-links](rustdoc-links/index.md)
8
+
- [Getting started](rustdoc-links/getting-started.md)
9
+
- [Motivation](rustdoc-links/motivation.md)
10
+
- [Supported syntax](rustdoc-links/supported-syntax.md)
11
+
- [Name resolution](rustdoc-links/name-resolution.md)
12
+
- [Workspace layout](rustdoc-links/workspace-layout.md)
13
+
- [Caching](rustdoc-links/caching.md)
14
+
- [Standalone usage](rustdoc-links/standalone-usage.md)
15
+
- [Continuous integration](rustdoc-links/continuous-integration.md)
16
+
- [Configuration](rustdoc-links/configuration.md)
17
+
- [Known issues](rustdoc-links/known-issues.md)
18
18
19
19
---
20
20
21
-
- [link-forever](link-forever/index.md)
22
-
- [Feature sheet](link-forever/features.md)
23
-
- [`{{#include}}` workarounds](link-forever/working-with-include.md)
24
-
- [Continuous integration](link-forever/continuous-integration.md)
25
-
- [Configuration](link-forever/configuration.md)
26
-
- [Known issues](link-forever/known-issues.md)
21
+
- [mdbook-permalinks](permalinks/index.md)
22
+
- [Feature sheet](permalinks/features.md)
23
+
- [`{{#include}}` workarounds](permalinks/working-with-include.md)
24
+
- [Continuous integration](permalinks/continuous-integration.md)
25
+
- [Configuration](permalinks/configuration.md)
26
+
- [Known issues](permalinks/known-issues.md)
27
27
28
28
---
29
29
-2
docs/src/_internal/README.md
-2
docs/src/_internal/README.md
-1
docs/src/index.md
-1
docs/src/index.md
···
1
-
{{#include ../../crates/mdbookkit/README.md}}
docs/src/link-forever/configuration.md
docs/src/permalinks/configuration.md
docs/src/link-forever/configuration.md
docs/src/permalinks/configuration.md
docs/src/link-forever/continuous-integration.md
docs/src/permalinks/continuous-integration.md
docs/src/link-forever/continuous-integration.md
docs/src/permalinks/continuous-integration.md
docs/src/link-forever/features.md
docs/src/permalinks/features.md
docs/src/link-forever/features.md
docs/src/permalinks/features.md
docs/src/link-forever/index.md
docs/src/permalinks/index.md
docs/src/link-forever/index.md
docs/src/permalinks/index.md
docs/src/link-forever/known-issues.md
docs/src/permalinks/known-issues.md
docs/src/link-forever/known-issues.md
docs/src/permalinks/known-issues.md
docs/src/link-forever/media/error-reporting-canonical-urls.png
docs/src/permalinks/media/error-reporting-canonical-urls.png
docs/src/link-forever/media/error-reporting-canonical-urls.png
docs/src/permalinks/media/error-reporting-canonical-urls.png
docs/src/link-forever/media/error-reporting.png
docs/src/permalinks/media/error-reporting.png
docs/src/link-forever/media/error-reporting.png
docs/src/permalinks/media/error-reporting.png
docs/src/link-forever/working-with-include.md
docs/src/permalinks/working-with-include.md
docs/src/link-forever/working-with-include.md
docs/src/permalinks/working-with-include.md
+5
-6
docs/src/rustdoc-link/caching.md
docs/src/rustdoc-links/caching.md
+5
-6
docs/src/rustdoc-link/caching.md
docs/src/rustdoc-links/caching.md
···
1
1
# Caching
2
2
3
-
By default, `mdbook-rustdoc-link` spawns a fresh `rust-analyzer` process every time it
4
-
runs. rust-analyzer must then reindex your entire project before being able to resolve
5
-
links.
3
+
By default, the preprocessor spawns a fresh `rust-analyzer` process every time it runs.
4
+
rust-analyzer must then reindex your entire project before being able to resolve links.
6
5
7
6
This makes the `mdbook serve` command significantly less responsive, which gets worse if
8
7
your project contains a large number of dependencies. It is as if for every live reload,
···
13
12
14
13
## Enabling caching
15
14
16
-
In `book.toml`, in the `[preprocessor.rustdoc-link]` table, set
15
+
In `book.toml`, in the `[preprocessor.rustdoc-links]` table, set
17
16
[`cache-dir`](configuration.md#cache-dir) to the relative path of a directory of your
18
17
choice, _outside_ of your book's `build-dir`, for example:
19
18
20
19
```toml
21
-
[preprocessor.rustdoc-link]
20
+
[preprocessor.rustdoc-links]
22
21
cache-dir = "cache"
23
22
# You could also point to an arbitrary directory in target/
24
23
```
···
102
101
`rust-analyzer` instance per cargo workspace."
103
102
104
103
In theory, in an IDE setting (e.g. with VS Code), one could setup the IDE and
105
-
`mdbook-rustdoc-link` to both connect to the same `ra-multiplex` server. Then the
104
+
`mdbook-rustdoc-links` to both connect to the same `ra-multiplex` server. Then the
106
105
preprocessor doesn't need to wait for cache priming (the cache is already warm from IDE
107
106
use). Changes in the workspace could also be reflected in subsequent builds without the
108
107
preprocessor being aware of them (because the IDE is doing the synchronizing).
-20
docs/src/rustdoc-link/configuration.md
-20
docs/src/rustdoc-link/configuration.md
···
1
-
# Configuration
2
-
3
-
This page lists all options for the preprocessor.
4
-
5
-
For use in `book.toml`, configure under the `[preprocessor.rustdoc-link]` table using
6
-
the keys below, for example:
7
-
8
-
```toml
9
-
[preprocessor.rustdoc-link]
10
-
rust-analyzer = "path/to/rust-analyzer --option ..."
11
-
```
12
-
13
-
For use [on the command line](standalone-usage.md), use the keys as long arguments, for
14
-
example:
15
-
16
-
```bash
17
-
mdbook-rustdoc-link markdown --rust-analyzer "..."
18
-
```
19
-
20
-
<rustdoc-link-options>(autogenerated)</rustdoc-link-options>
+5
-6
docs/src/rustdoc-link/continuous-integration.md
docs/src/rustdoc-links/continuous-integration.md
+5
-6
docs/src/rustdoc-link/continuous-integration.md
docs/src/rustdoc-links/continuous-integration.md
···
1
1
# Continuous integration
2
2
3
-
This page gives information and tips for using `mdbook-rustdoc-link` in a continuous
4
-
integration (CI) environment. The preprocessor optimizes some behaviors for CI, in terms
5
-
of error handling, logging, etc.
3
+
The preprocessor optimizes some behaviors for continuous integration (CI) environments,
4
+
in terms of error handling, logging, etc.
6
5
7
6
## Detecting CI
8
7
···
51
50
when a link fails to resolve, it prints them as warnings but continues to run. This is
52
51
so that your book continues to build via `mdbook serve` while you make edits.
53
52
54
-
When running in CI, all such warnings are promoted to errors. The preprocessor will exit
55
-
with a non-zero status code which will fail your build. This is to prevent outdated or
56
-
incorrect links from being accidentally deployed.
53
+
**When running in CI, all such warnings are promoted to errors by default.** The
54
+
preprocessor will exit with a non-zero status code which will fail your build. This is
55
+
to prevent outdated or incorrect links from being accidentally deployed.
57
56
58
57
You can explicitly control this behavior using the
59
58
[`fail-on-warnings`](configuration.md#fail-on-warnings) option.
+4
-4
docs/src/rustdoc-link/getting-started.md
docs/src/rustdoc-links/getting-started.md
+4
-4
docs/src/rustdoc-link/getting-started.md
docs/src/rustdoc-links/getting-started.md
···
14
14
2. Install the preprocessor:
15
15
16
16
```
17
-
cargo install mdbookkit --features rustdoc-link
17
+
cargo install mdbook-rustdoc-links
18
18
```
19
19
20
20
Alternatively, you may obtain precompiled binaries from [GitHub
···
30
30
[book]
31
31
title = "My Book"
32
32
33
-
[preprocessor.rustdoc-link]
34
-
# mdBook will run `mdbook-rustdoc-link`
33
+
[preprocessor.rustdoc-links]
34
+
# mdBook will execute the command `mdbook-rustdoc-links`
35
35
after = ["links"]
36
36
# mdBook will run this preprocessor after the default `links` preprocessor.
37
37
# This is recommended. It allows the preprocessor to see text embedded
···
74
74
75
75
> [!TIP]
76
76
>
77
-
> `mdbook-rustdoc-link` makes use of rust-analyzer's ["Open Docs"][open-docs] feature,
77
+
> `mdbook-rustdoc-links` makes use of rust-analyzer's ["Open Docs"][open-docs] feature,
78
78
> which resolves links to documentation given a symbol.
79
79
>
80
80
> Items from `std` will generate links to <https://doc.rust-lang.org>, while items from
+19
-16
docs/src/rustdoc-link/index.md
docs/src/rustdoc-links/index.md
+19
-16
docs/src/rustdoc-link/index.md
docs/src/rustdoc-links/index.md
···
3
3
<div class="hidden">
4
4
5
5
**For best results, view this page at
6
-
<https://tonywu6.github.io/mdbookkit/rustdoc-link>.**
6
+
<https://tonywu6.github.io/mdbookkit/rustdoc-links>.**
7
7
8
8
</div>
9
9
···
45
45
46
46
For **writing documentation** —
47
47
48
-
- To learn more about how the preprocessor resolves items into links, including
49
-
[feature-gated items](name-resolution.md#feature-gated-items), see
50
-
[Name resolution](name-resolution.md).
51
-
- To learn how to link to additional items such as
48
+
- [Supported syntax](supported-syntax.md): Full list of link syntax with examples. Know
49
+
how to link to additional items such as
52
50
[functions, macros](supported-syntax.md#functions-and-macros), and
53
-
[implementors](supported-syntax.md#implementors-and-fully-qualified-syntax), see
54
-
[Supported syntax](supported-syntax.md).
51
+
[implementors](supported-syntax.md#implementors-and-fully-qualified-syntax).
52
+
- [Name resolution](name-resolution.md): Understand how the preprocessor find Rust
53
+
items, including
54
+
[when items are gated behind features](name-resolution.md#feature-gated-items).
55
55
56
56
For **making the preprocessor work with your project** —
57
57
58
-
- If you use [Cargo workspaces][workspaces], see specific instructions in
59
-
[Workspace layout](workspace-layout.md).
60
-
- If you are working on a large project, and processing is taking a long time, see the
61
-
discussion in [Caching](caching.md).
58
+
- [Workspace layout](workspace-layout.md): Setup and options suitable for [Cargo
59
+
workspaces][workspaces].
60
+
- [Caching](caching.md): If you are working on a large project and processing is taking
61
+
a long time.
62
62
63
63
For **additional usage information** —
64
64
65
-
- You can use this as a standalone command line tool: see
66
-
[Standalone usage](standalone-usage.md).
67
-
- For tips on using this in CI, see [Continuous integration](continuous-integration.md).
68
-
- For all available options and how to set them, see [Configuration](configuration.md).
69
-
- Finally, review [Known issues](known-issues.md) and limitations.
65
+
- [Standalone usage](standalone-usage.md): Use the preprocessor as a standalone command
66
+
line tool.
67
+
- [Continuous integration](continuous-integration.md): Information for running the
68
+
preprocessor in CI environments, including
69
+
[logging](continuous-integration.md#logging) and
70
+
[failing a build when there are bad links](continuous-integration.md#error-handling).
71
+
- [Configuration](configuration.md): List of available options.
72
+
- [Known issues](known-issues.md) and limitations.
70
73
71
74
Happy linking!
72
75
+5
-5
docs/src/rustdoc-link/known-issues.md
docs/src/rustdoc-links/known-issues.md
+5
-5
docs/src/rustdoc-link/known-issues.md
docs/src/rustdoc-links/known-issues.md
···
2
2
3
3
## Performance
4
4
5
-
`mdbook-rustdoc-link` itself doesn't need much processing power, but it invokes
5
+
`mdbook-rustdoc-links` itself doesn't need much processing power, but it invokes
6
6
rust-analyzer, which does a full scan of your workspace. The larger your workspace is,
7
7
the longer mdBook will have to wait for the preprocessor. This is the source of the
8
8
majority of the run time.
···
40
40
- The correct link is
41
41
[https://docs.rs/tokio-macros/2.5.0/tokio_macros/~~macro~~attr.main.html][tokio::main]
42
42
43
-
### Trait items
43
+
### Implemented items with the same name
44
44
45
45
Rust allows methods to have the same name if they are from different traits, and types
46
46
can implement the same trait multiple times if the trait is generic. All such methods
···
78
78
## Sites other than docs.rs
79
79
80
80
Currently, items from crates other than `std` always generate links that point to
81
-
<https://docs.rs>. `mdbook-rustdoc-link` does not yet support configuring alternative
82
-
URL prefixes.
81
+
<https://docs.rs>. The preprocessor does not yet support configuring alternative URL
82
+
prefixes.
83
83
84
84
## Wrong line numbers in diagnostics
85
85
···
96
96
97
97
This is an unfortunate limitation with mdBook's preprocessor architecture. Preprocessors
98
98
are run sequentially, with the next preprocessor receiving Markdown source rendered by
99
-
the previous one. If preprocessors running before `mdbook-rustdoc-link` modify Markdown
99
+
the previous one. If preprocessors running before the preprocessor modify Markdown
100
100
source in such ways that shift lines around, then the line numbers will look incorrect.
101
101
102
102
Unless mdBook somehow gains [source map][sourcemap] support, this problem is unlikely to
docs/src/rustdoc-link/media/error-reporting-wrong-line.png
docs/src/rustdoc-links/media/error-reporting-wrong-line.png
docs/src/rustdoc-link/media/error-reporting-wrong-line.png
docs/src/rustdoc-links/media/error-reporting-wrong-line.png
docs/src/rustdoc-link/media/error-reporting.png
docs/src/rustdoc-links/media/error-reporting.png
docs/src/rustdoc-link/media/error-reporting.png
docs/src/rustdoc-links/media/error-reporting.png
docs/src/rustdoc-link/media/open-docs.png
docs/src/rustdoc-links/media/open-docs.png
docs/src/rustdoc-link/media/open-docs.png
docs/src/rustdoc-links/media/open-docs.png
docs/src/rustdoc-link/media/screencap.webp
docs/src/rustdoc-links/media/screencap.webp
docs/src/rustdoc-link/media/screencap.webp
docs/src/rustdoc-links/media/screencap.webp
docs/src/rustdoc-link/media/standalone-usage.png
docs/src/rustdoc-links/media/standalone-usage.png
docs/src/rustdoc-link/media/standalone-usage.png
docs/src/rustdoc-links/media/standalone-usage.png
+2
-2
docs/src/rustdoc-link/motivation.md
docs/src/rustdoc-links/motivation.md
+2
-2
docs/src/rustdoc-link/motivation.md
docs/src/rustdoc-links/motivation.md
···
21
21
- You do want at least some reference links. It could quickly become cumbersome to find
22
22
and copy the correct links by hand, and even more so to maintain them over time.
23
23
24
-
`mdbook-rustdoc-link` is the tooling answer to these problems. _Effortless, correct, and
25
-
good practice — choose all three!_
24
+
`mdbook-rustdoc-links` is the tooling answer to these problems. _Effortless, correct,
25
+
and good practice — choose all three!_
26
26
27
27
> [!TIP]
28
28
>
+2
-2
docs/src/rustdoc-link/name-resolution.md
docs/src/rustdoc-links/name-resolution.md
+2
-2
docs/src/rustdoc-link/name-resolution.md
docs/src/rustdoc-links/name-resolution.md
···
88
88
such items, configure the necessary features:
89
89
90
90
```toml
91
-
[preprocessor.rustdoc-link]
91
+
[preprocessor.rustdoc-links]
92
92
cargo-features = ["clap/unstable-doc"]
93
93
```
94
94
95
-
Then, specify the item as normal:
95
+
Then, specify the item as usual:
96
96
97
97
> ```md
98
98
> [Tutorial for clap's Derive API][clap::_derive::_tutorial]
+4
-4
docs/src/rustdoc-link/standalone-usage.md
docs/src/rustdoc-links/standalone-usage.md
+4
-4
docs/src/rustdoc-link/standalone-usage.md
docs/src/rustdoc-links/standalone-usage.md
···
1
1
# Standalone usage
2
2
3
-
You can use `mdbook-rustdoc-link` as a standalone Markdown processor via the `markdown`
3
+
You can use `mdbook-rustdoc-links` as a standalone Markdown processor via the `markdown`
4
4
subcommand: send your Markdown through stdin, and receive the result through stdout, for
5
5
example:
6
6
7
7
```bash
8
-
mdbook-rustdoc-link markdown < README.md
8
+
mdbook-rustdoc-links markdown < README.md
9
9
```
10
10
11
11
The command accepts as arguments all [options](configuration.md) configurable in
12
12
`book.toml`, such as [`--cache-dir`](configuration.md#cache-dir). Run
13
-
`mdbook-rustdoc-link markdown --help` to see them.
13
+
`mdbook-rustdoc-links markdown --help` to see them.
14
14
15
15
<figure id="media-open-docs">
16
-
<img src="media/standalone-usage.png" alt="example using mdbook-rustdoc-link as a command line tool">
16
+
<img src="media/standalone-usage.png" alt="example using mdbook-rustdoc-links as a command line tool">
17
17
</figure>
18
18
19
19
<style>
+1
-1
docs/src/rustdoc-link/supported-syntax.md
docs/src/rustdoc-links/supported-syntax.md
+1
-1
docs/src/rustdoc-link/supported-syntax.md
docs/src/rustdoc-links/supported-syntax.md
+2
-2
docs/src/rustdoc-link/workspace-layout.md
docs/src/rustdoc-links/workspace-layout.md
+2
-2
docs/src/rustdoc-link/workspace-layout.md
docs/src/rustdoc-links/workspace-layout.md
···
21
21
22
22
## Using the `manifest-dir` option
23
23
24
-
In your `book.toml`, in the `[preprocessor.rustdoc-link]` table, set the
24
+
In your `book.toml`, in the `[preprocessor.rustdoc-links]` table, set the
25
25
[`manifest-dir`](configuration.md#manifest-dir) option to the relative path to a member
26
26
package.
27
27
···
43
43
Then in your `book.toml`:
44
44
45
45
```toml
46
-
[preprocessor.rustdoc-link]
46
+
[preprocessor.rustdoc-links]
47
47
manifest-dir = "../crates/fancy-crate"
48
48
```
49
49
+18
docs/src/rustdoc-links/configuration.md
+18
docs/src/rustdoc-links/configuration.md
···
1
+
# Configuration
2
+
3
+
This page lists all options for the preprocessor.
4
+
5
+
Configure options in the `[preprocessor.rustdoc-links]` table using the keys below, for
6
+
example:
7
+
8
+
```toml
9
+
[preprocessor.rustdoc-links]
10
+
rust-analyzer = "path/to/rust-analyzer --option ..."
11
+
```
12
+
13
+
For use [on the command line](standalone-usage.md), specify options via arguments, for
14
+
example:
15
+
16
+
```bash
17
+
mdbook-rustdoc-links markdown --rust-analyzer "..."
18
+
```