docs: Use mdbook admonitions by epage · Pull Request #17384 · rust-lang/cargo

epage · 2026-08-22T00:14:52Z

What does this PR try to resolve?

Establishing a pattern of their use which should reduce needing review feedback like #17382 (comment)

See https://rust-lang.github.io/mdBook/format/markdown.html#admonitions

How to test and review this PR?

rustbot · 2026-08-22T00:14:57Z

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @epage, @weihanglo
@epage, @weihanglo expanded to epage, weihanglo

weihanglo · 2026-08-22T00:18:26Z

I was planning to do it tonight as well. I am glad I haven't yet started

weihanglo

We probably don't want to spend too much time debating where to use which kind of admonitions.

Feel free to merge this when it is ready

View changes since this review

epage · 2026-08-22T01:20:50Z

Been meaning to do this ever since it came up

weihanglo

Some other "tips" need to update:

cargo/doc/book/src/reference/environment-variables.md

Lines 387 to 390 in 9243bb7

    
             > **Tip:** For a typed API to read these values, consider using the [`build-rs`] 
        
             > crate instead of parsing environment variables manually. Also note that 
        
             > `CARGO_CFG_*` variables should be used instead of the `cfg!` macro or `#[cfg]` 
        
             > attribute in build scripts, those check the *host* platform, not the *target*.

cargo/doc/contrib/src/process/working-on-cargo.md

Lines 133 to 135 in 9243bb7

    
           > **tip:** Prefer atomic commits where each commit is a single, complete, and coherent unit of work. 
        
           > For example, if your feature work leads to renaming a module, make the rename its own commit. 
        
           > However, adding an internal function that is unused is not complete or coherent.

View changes since this review

weihanglo · 2026-08-22T16:39:05Z

So looks like https://github.com/rust-lang/cargo/actions/runs/32574966922/job/97041213022?pr=17384 continue failing because it runs on nightly.

# fine
cargo +stable doc --workspace --document-private-items --no-deps --keep-going
# stuck at `varisat`
cargo ++nightly-2026-08-22 doc --workspace --document-private-items --no-deps --keep-going

And the memory usage seems to go unbound.

weihanglo · 2026-08-22T16:52:01Z

So

# works
env RUSTFLAGS=-Znext-solver=coherence cargo +nightly-2026-08-22 check -p varisat

# stuck
env RUSTFLAGS=-Znext-solver=globally cargo +nightly-2026-08-22 check -p varisat

so something worth reporting to rust-lang/rust#160895.

…ng#17385) ### What does this PR try to resolve? next trait resolver might have bugs dealing with it, but anyway we care less about intra doclinks for resolver-tests, and it anyway builds in clippy jobs. ### How to test and review this PR? See <rust-lang#17384 (comment)>: ``` # works env RUSTFLAGS=-Znext-solver=coherence cargo +nightly-2026-08-22 check -p varisat # stuck env RUSTFLAGS=-Znext-solver=globally cargo +nightly-2026-08-22 check -p varisat ```

rustbot · 2026-08-22T22:30:22Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

Update cargo submodule 7 commits in e8cb624d5701824f46a2ec5873cfd59ee3d2f66c..94ba974179df2adb3c911fadf361f03b84aa8f14 2026-08-22 00:23:45 +0000 to 2026-08-25 18:16:11 +0000 - feat(diag): Stabilize cargo-lints (rust-lang/cargo#17298) - chore(deps): Update partial_ref to v0.3.4 (rust-lang/cargo#17392) - refactor: remove ad-hoc `subslice_range` (rust-lang/cargo#17390) - docs(changelog): move build-dir new layout to Changed (rust-lang/cargo#17387) - chore(deps): update msrv (1 version) to v1.98 (rust-lang/cargo#17386) - docs: Use mdbook admonitions (rust-lang/cargo#17384) - chore(ci): exclude resolver-tests from intra doc link checks (rust-lang/cargo#17385)

Update cargo submodule 26 commits in e8cb624d5701824f46a2ec5873cfd59ee3d2f66c..b2e9d5f9db3fb1c454ab84f10c16508984a266e2 2026-08-22 00:23:45 +0000 to 2026-09-02 14:49:16 +0000 - fix(parser): Resolve theoretical use-after-free (rust-lang/cargo#17428) - fix(trim-paths)!: remove default scope from release profile (rust-lang/cargo#17424) - fix(git): Use git's 429 retry, when available (rust-lang/cargo#17422) - Avoid passing search path (-L) args when they are passed as --extern (rust-lang/cargo#17410) - chore(deps): update crate-ci/typos action to v1.50.0 (rust-lang/cargo#17417) - test: Move -Z onto its own line (rust-lang/cargo#17416) - chore(triagebot): enable `@rustbot merge/delegate` (rust-lang/cargo#17415) - Micro-optimize two package dir functions (rust-lang/cargo#17413) - perf: Do not build SBOM if user has not set build.sbom (rust-lang/cargo#17412) - feat(manifest)!: implement feature-metadata RFC3416 (rust-lang/cargo#15056) - Cargo profiling improvements (rust-lang/cargo#17411) - test(git): Remove gix override run in CI and the mode in code (rust-lang/cargo#17405) - perf(git): Reduce extra work when using git-cli (rust-lang/cargo#17406) - feat(resolver): Stabilize min-publish-age (rust-lang/cargo#17335) - fix(git): Remove ref status update when showing progress (rust-lang/cargo#17400) - revert: refactor: move sysroot lookup to GlobalContext (rust-lang/cargo#17401) - fix(run): Printing a new line to avoid overwriting error code after \r (rust-lang/cargo#17373) - fix(trim-paths): custom workspace-relative member paths remap (rust-lang/cargo#17366) - fix(home): rustdoc lint (rust-lang/cargo#17394) - feat(diag): Stabilize cargo-lints (rust-lang/cargo#17298) - chore(deps): Update partial_ref to v0.3.4 (rust-lang/cargo#17392) - refactor: remove ad-hoc `subslice_range` (rust-lang/cargo#17390) - docs(changelog): move build-dir new layout to Changed (rust-lang/cargo#17387) - chore(deps): update msrv (1 version) to v1.98 (rust-lang/cargo#17386) - docs: Use mdbook admonitions (rust-lang/cargo#17384) - chore(ci): exclude resolver-tests from intra doc link checks (rust-lang/cargo#17385)

rustbot added the A-documenting-cargo-itself Area: Cargo's documentation label Aug 22, 2026

rustbot assigned weihanglo Aug 22, 2026

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 22, 2026

weihanglo reviewed Aug 22, 2026

View reviewed changes

Comment thread doc/book/src/reference/features.md Outdated

weihanglo approved these changes Aug 22, 2026

View reviewed changes

epage force-pushed the admonition branch from 191ac9c to a120420 Compare August 22, 2026 01:20

epage enabled auto-merge August 22, 2026 01:21

epage added this pull request to the merge queue Aug 22, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Aug 22, 2026

weihanglo added this pull request to the merge queue Aug 22, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Aug 22, 2026

weihanglo reviewed Aug 22, 2026

View reviewed changes

Comment thread doc/book/src/appendix/git-authentication.md Outdated

Comment thread doc/book/src/reference/manifest.md Outdated

Comment thread doc/book/src/reference/config.md Outdated

Comment thread doc/book/src/reference/config.md Outdated

weihanglo force-pushed the admonition branch from a120420 to 69b2d2a Compare August 22, 2026 13:09

weihanglo enabled auto-merge August 22, 2026 13:11

weihanglo mentioned this pull request Aug 22, 2026

chore(ci): exclude resolver-tests from intra doc link checks #17385

Merged

weihanglo mentioned this pull request Aug 22, 2026

Next-generation trait solver enabled on nightly rust-lang/rust#160895

Open

epage added 3 commits August 22, 2026 18:29

docs: Switch to NOTE admonitions

7648815

docs: Switch to TIP admonitions

31ccf24

docs: Use more semantically nuanced admmonitions

b0cd833

weihanglo force-pushed the admonition branch from 69b2d2a to b0cd833 Compare August 22, 2026 22:30

weihanglo added this pull request to the merge queue Aug 22, 2026

Merged via the queue into rust-lang:master with commit ed4cb4f Aug 22, 2026
29 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 22, 2026

rustbot mentioned this pull request Aug 22, 2026

docs: describe why package.authors is deprecated #17332

Draft

lcnr mentioned this pull request Aug 23, 2026

rustc hangs when compiling varisat (-Znext-solver) rust-lang/rust#161575

Open

weihanglo mentioned this pull request Aug 25, 2026

Update cargo submodule rust-lang/rust#161789

Merged

rustbot added this to the 1.100.0 milestone Sep 2, 2026

This was referenced Sep 15, 2026

[replay #17384] docs: Use mdbook admonitions Pufferfish-Merget/bench-cargo#5

Closed

[replay #17384] docs: Use mdbook admonitions Pufferfish-Merget/bench-cargo#17

Closed

Navigation Menu

Uh oh!

docs: Use mdbook admonitions - #17384

docs: Use mdbook admonitions#17384
weihanglo merged 3 commits into
rust-lang:masterfrom
epage:admonition

epage commented Aug 22, 2026

Uh oh!

rustbot commented Aug 22, 2026

Uh oh!

weihanglo commented Aug 22, 2026

Uh oh!

Uh oh!

weihanglo left a comment •

edited by rustbot

Loading

Uh oh!

epage commented Aug 22, 2026

Uh oh!

Uh oh!

Uh oh!

weihanglo left a comment •

edited by rustbot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weihanglo commented Aug 22, 2026

Uh oh!

weihanglo commented Aug 22, 2026

Uh oh!

rustbot commented Aug 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	> Tip: For a typed API to read these values, consider using the [`build-rs`]
	> crate instead of parsing environment variables manually. Also note that
	> `CARGO_CFG_*` variables should be used instead of the `cfg!` macro or `#[cfg]`
	> attribute in build scripts, those check the host platform, not the target.

	> tip: Prefer atomic commits where each commit is a single, complete, and coherent unit of work.
	> For example, if your feature work leads to renaming a module, make the rename its own commit.
	> However, adding an internal function that is unused is not complete or coherent.

Uh oh!

Conversation

epage commented Aug 22, 2026

What does this PR try to resolve?

How to test and review this PR?

Uh oh!

rustbot commented Aug 22, 2026

Uh oh!

weihanglo commented Aug 22, 2026

Uh oh!

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epage commented Aug 22, 2026

Uh oh!

Uh oh!

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weihanglo commented Aug 22, 2026

Uh oh!

weihanglo commented Aug 22, 2026

Uh oh!

rustbot commented Aug 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

weihanglo left a comment •

edited by rustbot

Loading

weihanglo left a comment •

edited by rustbot

Loading