toolkit for mdBook [mirror of my GitHub repo]
docs.tonywu.dev/mdbookkit/
permalinks
rust-analyzer
mdbook
docs: add logging documentation
+106
-35
+2
Cargo.lock
+2
Cargo.lock
+1
Cargo.toml
+1
Cargo.toml
-15
README.md
-15
README.md
···
8
8
[](https://tonywu6.github.io/mdbookkit/)
9
9
[](/LICENSE-APACHE.md)
10
10
11
-
## [Read the book](https://tonywu6.github.io/mdbookkit/)
12
-
13
-
You may be looking for:
14
-
15
-
[**`mdbook-rustdoc-link`**](https://tonywu6.github.io/mdbookkit/rustdoc-link/)
16
-
17
11
<!-- prettier-ignore-start -->
18
-
19
-
- [Install & use](https://tonywu6.github.io/mdbookkit/rustdoc-link/getting-started#install)
20
-
| [Using in CI](https://tonywu6.github.io/mdbookkit/rustdoc-link/continuous-integration)
21
-
| [Caching](https://tonywu6.github.io/mdbookkit/rustdoc-link/caching)
22
-
23
-
[**`mdbook-link-forever`**](https://tonywu6.github.io/mdbookkit/link-forever/)
24
-
25
-
- [Install & use](https://tonywu6.github.io/mdbookkit/link-forever/#getting-started)
26
-
| [Using in CI](https://tonywu6.github.io/mdbookkit/link-forever/continuous-integration)
27
12
28
13
[mdBook]: https://rust-lang.github.io/mdBook/
29
14
+4
-4
crates/mdbook-permalinks/src/link.rs
+4
-4
crates/mdbook-permalinks/src/link.rs
···
1
1
use std::{fmt::Debug, ops::Range};
2
2
3
3
use mdbook_markdown::pulldown_cmark::{CowStr, Event, LinkType, Tag, TagEnd};
4
-
use tracing::{debug, trace};
4
+
use tracing::trace;
5
5
use url::Url;
6
6
7
7
#[derive(Debug, Default, Clone, thiserror::Error)]
···
97
97
fn update(&mut self, link: impl Into<CowStr<'a>>) {
98
98
let old = &*self.link.clone();
99
99
self.link = link.into();
100
-
debug!(status = ?self.status, ?old, new = ?&*self.link);
100
+
trace!(status = ?self.status, ?old, new = ?&*self.link);
101
101
}
102
102
103
103
#[inline]
104
104
pub fn unchanged(&mut self) {
105
105
self.status = LinkStatus::Unchanged;
106
-
debug!(status = ?self.status, link = ?&*self.link);
106
+
trace!(status = ?self.status, link = ?&*self.link);
107
107
}
108
108
109
109
#[inline]
110
110
pub fn unreachable(&mut self, errors: Vec<(Url, PathStatus)>) {
111
111
self.status = LinkStatus::Unreachable(errors);
112
-
debug!(status = ?self.status, link = ?&*self.link);
112
+
trace!(status = ?self.status, link = ?&*self.link);
113
113
}
114
114
115
115
fn emit(&self) -> Tag<'a> {
+3
-3
crates/mdbook-permalinks/src/page.rs
+3
-3
crates/mdbook-permalinks/src/page.rs
···
108
108
info!(
109
109
"Processed {total}: {permalink}; {rewritten}; {unreachable}; {unchanged}",
110
110
total = plural!(total, "link"),
111
-
permalink = plural!(permalink, "generated permalink"),
112
-
rewritten = plural!(rewritten, "rewritten as paths", "rewritten as paths"),
113
-
unreachable = plural!(unreachable, "unreachable path"),
111
+
permalink = plural!(permalink, "permalink"),
112
+
rewritten = plural!(rewritten, "book link"),
113
+
unreachable = plural!(unreachable, "inaccessible path"),
114
114
unchanged = plural!(unchanged + ignored + error, "unchanged", "unchanged"),
115
115
);
116
116
}
+1
-1
crates/mdbook-rustdoc-links/src/main.rs
+1
-1
crates/mdbook-rustdoc-links/src/main.rs
+1
-1
crates/mdbookkit/Cargo.toml
+1
-1
crates/mdbookkit/Cargo.toml
···
32
32
tap = { workspace = true }
33
33
toml = { workspace = true }
34
34
tracing = { workspace = true }
35
-
tracing-subscriber = { version = "0.3.22", features = ["env-filter"] }
35
+
tracing-subscriber = { workspace = true, features = ["env-filter"] }
36
36
url = { workspace = true }
37
37
38
38
cargo-run-bin = { workspace = true, optional = true }
+6
-2
crates/mdbookkit/src/env.rs
+6
-2
crates/mdbookkit/src/env.rs
···
10
10
11
11
static CI: LazyLock<String> = LazyLock::new(|| std::env::var("CI").unwrap_or("".into()));
12
12
13
-
pub(crate) static MDBOOK_LOG: LazyLock<Option<String>> =
14
-
LazyLock::new(|| std::env::var("MDBOOK_LOG").ok());
13
+
pub(crate) static MDBOOK_LOG: LazyLock<Option<String>> = LazyLock::new(|| {
14
+
std::env::var("MDBOOK_LOG")
15
+
// mdBook v0.4.x
16
+
.or_else(|_| std::env::var("RUST_LOG"))
17
+
.ok()
18
+
});
15
19
16
20
#[inline]
17
21
pub fn is_ci() -> Option<&'static str> {
+2
docs/Cargo.toml
+2
docs/Cargo.toml
+2
-2
docs/src/SUMMARY.md
+2
-2
docs/src/SUMMARY.md
···
12
12
- [Workspace layout](rustdoc-links/workspace-layout.md)
13
13
- [Caching](rustdoc-links/caching.md)
14
14
- [Standalone usage](rustdoc-links/standalone-usage.md)
15
+
- [Logging](rustdoc-links/logging.md)
15
16
- [Continuous integration](rustdoc-links/continuous-integration.md)
16
17
- [Configuration](rustdoc-links/configuration.md)
17
18
- [Known issues](rustdoc-links/known-issues.md)
···
22
23
- [Getting started](permalinks/getting-started.md)
23
24
- [Features](permalinks/features.md)
24
25
- [More ways to link](permalinks/more-ways-to-link.md)
26
+
- [Logging](permalinks/logging.md)
25
27
- [Continuous integration](permalinks/continuous-integration.md)
26
28
- [Configuration](permalinks/configuration.md)
27
29
- [Known issues](permalinks/known-issues.md)
···
29
31
---
30
32
31
33
[CHANGELOG](CHANGELOG.md)
32
-
33
-
[INTERNAL: Repo README](./_internal/README.md)
-5
docs/src/_internal/README.md
-5
docs/src/_internal/README.md
+1
docs/src/index.md
+1
docs/src/index.md
···
1
+
{{#include ../../README.md}}
+12
docs/src/permalinks/logging.md
+12
docs/src/permalinks/logging.md
···
1
+
# Logging
2
+
3
+
With the environment variables `MDBOOK_LOG` and `CI`, you can control how the
4
+
preprocessor emits logs and diagnostic information.
5
+
6
+
## Output style
7
+
8
+
{{#include ../snippets/logging/output-style.md}}
9
+
10
+
## `MDBOOK_LOG`
11
+
12
+
{{#include ../snippets/logging/env-var.md}}
+37
docs/src/rustdoc-links/logging.md
+37
docs/src/rustdoc-links/logging.md
···
1
+
# Logging
2
+
3
+
With the environment variables `MDBOOK_LOG` and `CI`, you can control how the
4
+
preprocessor emits logs and diagnostic information.
5
+
6
+
## Output style
7
+
8
+
{{#include ../snippets/logging/output-style.md}}
9
+
10
+
## `MDBOOK_LOG`
11
+
12
+
{{#include ../snippets/logging/env-var.md}}
13
+
14
+
## Link report
15
+
16
+
Upon finishing, the preprocessor can display a list of all supported Rust items it finds
17
+
in the book and the URLs generated for each item. The list is sorted alphabetically by
18
+
item paths. This can be used to, for example, monitor any changes to the generated links
19
+
between builds.
20
+
21
+
To enable this, add the `link-report=debug` directive to `MDBOOK_LOG`, for example:
22
+
`MDBOOK_LOG=info,link-report=debug`.
23
+
24
+
> [!TIP]
25
+
>
26
+
> You most likely want to include at least an `info` directive in the variable:
27
+
>
28
+
> - `MDBOOK_LOG=info,link-report=debug` enables `link-report` on top of existing logs.
29
+
> - `MDBOOK_LOG=link-report=debug` will _completely disable_ all other logging,
30
+
> including from mdBook itself.
31
+
32
+
> [!TIP]
33
+
>
34
+
> The displayed items are deduplicated and do not contain the links' locations within
35
+
> the book. To see their locations (in the format of `path:line:column`), enable `debug`
36
+
> for the entire preprocessor, for example, `MDBOOK_LOG=info,mdbook_rustdoc_links=debug`
37
+
> or `MDBOOK_LOG=debug`.
+2
-2
docs/src/snippets/detecting-ci.md
+2
-2
docs/src/snippets/detecting-ci.md
···
13
13
14
14
<!-- prettier-ignore-start -->
15
15
16
-
[github-actions-ci]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
17
-
[gitlab-ci]: https://docs.gitlab.com/ci/variables/predefined_variables/
16
+
[github-actions-ci]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables
17
+
[gitlab-ci]: https://docs.gitlab.com/ci/variables/predefined_variables/#predefined-variables
18
18
19
19
<!-- prettier-ignore-end -->
+26
docs/src/snippets/logging/env-var.md
+26
docs/src/snippets/logging/env-var.md
···
1
+
The `MDBOOK_LOG` environment variable allows you to control the verbosity of logging
2
+
messages. The same variable also controls [mdBook's logging output][mdbook-init-logger].
3
+
4
+
The variable has semantics similar to the commonly seen `RUST_LOG` variable. For
5
+
example:
6
+
7
+
- `MDBOOK_LOG=info` enables logging at the `info` (regular) level. The preprocessor will
8
+
emit the same amount of information, including diagnostics, as when the variable is
9
+
not set, except graphical output styles are not used (see [above](#output-style)).
10
+
11
+
- `MDBOOK_LOG=debug` enables `debug` (more verbose) logging.
12
+
13
+
The variable is supported by `tracing-subscriber`. See
14
+
[`EnvFilter`][tracing_subscriber::filter::EnvFilter] for the complete usage info.
15
+
16
+
> [!NOTE]
17
+
>
18
+
> mdBook [v0.4.x uses the `RUST_LOG` variable][mdbook-init-logger-v0.4] instead of
19
+
> `MDBOOK_LOG`. This preprocessor supports both, with `MDBOOK_LOG` taking precedence.
20
+
21
+
<!-- prettier-ignore-start -->
22
+
23
+
[mdbook-init-logger]: https://github.com/rust-lang/mdBook/blob/v0.5.2/src/main.rs#L94-L97
24
+
[mdbook-init-logger-v0.4]: https://github.com/rust-lang/mdBook/blob/v0.4.52/src/main.rs#L111-L112
25
+
26
+
<!-- prettier-ignore-end -->
+6
docs/src/snippets/logging/output-style.md
+6
docs/src/snippets/logging/output-style.md
···
1
+
By default, the preprocessor reports progress using a spinner, and diagnostic
2
+
information (such as broken links) are displayed in a graphical manner, similar to how
3
+
rustc emits errors.
4
+
5
+
If `MDBOOK_LOG` is set, or if [`CI=true`](continuous-integration.md), then all messages
6
+
are emitted as logs instead.