From 3e6f950d66008a7a15f38d10d5b19707c06602c7 Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <hopsi@tuta.io>
Date: Thu, 17 Jul 2025 06:09:15 +0200
Subject: [PATCH 1/5] avoid the need to specify if toc should be generated

- this removes one external dependency, mdbook-toc
- this steals code from rustc book
---
 .../rustc-dev-guide/.github/workflows/ci.yml  |   4 +-
 src/doc/rustc-dev-guide/README.md             |   6 +-
 src/doc/rustc-dev-guide/book.toml             |  11 +-
 src/doc/rustc-dev-guide/pagetoc.css           |  84 ++++++++++++++
 src/doc/rustc-dev-guide/pagetoc.js            | 104 ++++++++++++++++++
 5 files changed, 198 insertions(+), 11 deletions(-)
 create mode 100644 src/doc/rustc-dev-guide/pagetoc.css
 create mode 100644 src/doc/rustc-dev-guide/pagetoc.js

diff --git a/src/doc/rustc-dev-guide/.github/workflows/ci.yml b/src/doc/rustc-dev-guide/.github/workflows/ci.yml
index daf5223cbd4ac..6eabb999fb013 100644
--- a/src/doc/rustc-dev-guide/.github/workflows/ci.yml
+++ b/src/doc/rustc-dev-guide/.github/workflows/ci.yml
@@ -17,7 +17,6 @@ jobs:
       MDBOOK_VERSION: 0.4.48
       MDBOOK_LINKCHECK2_VERSION: 0.9.1
       MDBOOK_MERMAID_VERSION: 0.12.6
-      MDBOOK_TOC_VERSION: 0.11.2
       MDBOOK_OUTPUT__LINKCHECK__FOLLOW_WEB_LINKS: ${{ github.event_name != 'pull_request' }}
       DEPLOY_DIR: book/html
       BASE_SHA: ${{ github.event.pull_request.base.sha }}
@@ -34,7 +33,7 @@ jobs:
         with:
           path: |
             ~/.cargo/bin
-          key: ${{ runner.os }}-${{ env.MDBOOK_VERSION }}--${{ env.MDBOOK_LINKCHECK2_VERSION }}--${{ env.MDBOOK_TOC_VERSION }}--${{ env.MDBOOK_MERMAID_VERSION }}
+          key: ${{ runner.os }}-${{ env.MDBOOK_VERSION }}--${{ env.MDBOOK_LINKCHECK2_VERSION }}--${{ env.MDBOOK_MERMAID_VERSION }}
 
       - name: Restore cached Linkcheck
         if: github.event_name == 'schedule'
@@ -57,7 +56,6 @@ jobs:
         run: |
           cargo install mdbook --version ${{ env.MDBOOK_VERSION }}
           cargo install mdbook-linkcheck2 --version ${{ env.MDBOOK_LINKCHECK2_VERSION }}
-          cargo install mdbook-toc --version ${{ env.MDBOOK_TOC_VERSION }}
           cargo install mdbook-mermaid --version ${{ env.MDBOOK_MERMAID_VERSION }}
 
       - name: Check build
diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md
index 5932da467ab2d..1ad895aeda2e1 100644
--- a/src/doc/rustc-dev-guide/README.md
+++ b/src/doc/rustc-dev-guide/README.md
@@ -43,7 +43,7 @@ rustdocs][rustdocs].
 To build a local static HTML site, install [`mdbook`](https://github.com/rust-lang/mdBook) with:
 
 ```
-cargo install mdbook mdbook-linkcheck2 mdbook-toc mdbook-mermaid
+cargo install mdbook mdbook-linkcheck2 mdbook-mermaid
 ```
 
 and execute the following command in the root of the repository:
@@ -67,8 +67,8 @@ ENABLE_LINKCHECK=1 mdbook serve
 
 ### Table of Contents
 
-We use `mdbook-toc` to auto-generate TOCs for long sections. You can invoke the preprocessor by
-including the `<!-- toc -->` marker at the place where you want the TOC.
+Each page has a TOC that is automatically generated by `pagetoc.js`.
+There is an associated `pagetoc.css`, for styling.
 
 ## Synchronizing josh subtree with rustc
 
diff --git a/src/doc/rustc-dev-guide/book.toml b/src/doc/rustc-dev-guide/book.toml
index b84b1e7548a86..daf237ed9081b 100644
--- a/src/doc/rustc-dev-guide/book.toml
+++ b/src/doc/rustc-dev-guide/book.toml
@@ -6,17 +6,18 @@ description = "A guide to developing the Rust compiler (rustc)"
 [build]
 create-missing = false
 
-[preprocessor.toc]
-command = "mdbook-toc"
-renderer = ["html"]
-
 [preprocessor.mermaid]
 command = "mdbook-mermaid"
 
 [output.html]
 git-repository-url = "https://github.com/rust-lang/rustc-dev-guide"
 edit-url-template = "https://github.com/rust-lang/rustc-dev-guide/edit/master/{path}"
-additional-js = ["mermaid.min.js", "mermaid-init.js"]
+additional-js = [
+  "mermaid.min.js",
+  "mermaid-init.js",
+  "pagetoc.js",
+]
+additional-css = ["pagetoc.css"]
 
 [output.html.search]
 use-boolean-and = true
diff --git a/src/doc/rustc-dev-guide/pagetoc.css b/src/doc/rustc-dev-guide/pagetoc.css
new file mode 100644
index 0000000000000..fa709194f3755
--- /dev/null
+++ b/src/doc/rustc-dev-guide/pagetoc.css
@@ -0,0 +1,84 @@
+/* Inspired by https://github.com/JorelAli/mdBook-pagetoc/tree/98ee241 (under WTFPL) */
+
+:root {
+    --toc-width: 270px;
+    --center-content-toc-shift: calc(-1 * var(--toc-width) / 2);
+}
+
+.nav-chapters {
+    /* adjust width of buttons that bring to the previous or the next page */
+    min-width: 50px;
+}
+
+@media only screen {
+    @media (max-width: 1179px) {
+        .sidebar-hidden #sidetoc {
+            display: none;
+        }
+    }
+
+    @media (max-width: 1439px) {
+        .sidebar-visible #sidetoc {
+            display: none;
+        }
+    }
+
+    @media (1180px <= width <= 1439px) {
+        .sidebar-hidden main {
+            position: relative;
+            left: var(--center-content-toc-shift);
+        }
+    }
+
+    @media (1440px <= width <= 1700px) {
+        .sidebar-visible main {
+            position: relative;
+            left: var(--center-content-toc-shift);
+        }
+    }
+
+    #sidetoc {
+        margin-left: calc(100% + 20px);
+    }
+    #pagetoc {
+        position: fixed;
+        /* adjust TOC width */
+        width: var(--toc-width);
+        height: calc(100vh - var(--menu-bar-height) - 0.67em * 4);
+        overflow: auto;
+    }
+    #pagetoc a {
+        border-left: 1px solid var(--sidebar-bg);
+        color: var(--fg);
+        display: block;
+        padding-bottom: 5px;
+        padding-top: 5px;
+        padding-left: 10px;
+        text-align: left;
+        text-decoration: none;
+    }
+    #pagetoc a:hover,
+    #pagetoc a.active {
+        background: var(--sidebar-bg);
+        color: var(--sidebar-active) !important;
+    }
+    #pagetoc .active {
+        background: var(--sidebar-bg);
+        color: var(--sidebar-active);
+    }
+    #pagetoc .pagetoc-H2 {
+        padding-left: 20px;
+    }
+    #pagetoc .pagetoc-H3 {
+        padding-left: 40px;
+    }
+    #pagetoc .pagetoc-H4 {
+        padding-left: 60px;
+    }
+}
+
+@media print {
+    #sidetoc {
+        display: none;
+    }
+}
diff --git a/src/doc/rustc-dev-guide/pagetoc.js b/src/doc/rustc-dev-guide/pagetoc.js
new file mode 100644
index 0000000000000..927a5b10749b5
--- /dev/null
+++ b/src/doc/rustc-dev-guide/pagetoc.js
@@ -0,0 +1,104 @@
+// Inspired by https://github.com/JorelAli/mdBook-pagetoc/tree/98ee241 (under WTFPL)
+
+let activeHref = location.href;
+function updatePageToc(elem = undefined) {
+    let selectedPageTocElem = elem;
+    const pagetoc = document.getElementById("pagetoc");
+
+    function getRect(element) {
+        return element.getBoundingClientRect();
+    }
+
+    function overflowTop(container, element) {
+        return getRect(container).top - getRect(element).top;
+    }
+
+    function overflowBottom(container, element) {
+        return getRect(container).bottom - getRect(element).bottom;
+    }
+
+    // We've not selected a heading to highlight, and the URL needs updating
+    // so we need to find a heading based on the URL
+    if (selectedPageTocElem === undefined && location.href !== activeHref) {
+        activeHref = location.href;
+        for (const pageTocElement of pagetoc.children) {
+            if (pageTocElement.href === activeHref) {
+                selectedPageTocElem = pageTocElement;
+            }
+        }
+    }
+
+    // We still don't have a selected heading, let's try and find the most
+    // suitable heading based on the scroll position
+    if (selectedPageTocElem === undefined) {
+        const margin = window.innerHeight / 3;
+
+        const headers = document.getElementsByClassName("header");
+        for (let i = 0; i < headers.length; i++) {
+            const header = headers[i];
+            if (selectedPageTocElem === undefined && getRect(header).top >= 0) {
+                if (getRect(header).top < margin) {
+                    selectedPageTocElem = header;
+                } else {
+                    selectedPageTocElem = headers[Math.max(0, i - 1)];
+                }
+            }
+            // a very long last section's heading is over the screen
+            if (selectedPageTocElem === undefined && i === headers.length - 1) {
+                selectedPageTocElem = header;
+            }
+        }
+    }
+
+    // Remove the active flag from all pagetoc elements
+    for (const pageTocElement of pagetoc.children) {
+        pageTocElement.classList.remove("active");
+    }
+
+    // If we have a selected heading, set it to active and scroll to it
+    if (selectedPageTocElem !== undefined) {
+        for (const pageTocElement of pagetoc.children) {
+            if (selectedPageTocElem.href.localeCompare(pageTocElement.href) === 0) {
+                pageTocElement.classList.add("active");
+                if (overflowTop(pagetoc, pageTocElement) > 0) {
+                    pagetoc.scrollTop = pageTocElement.offsetTop;
+                }
+                if (overflowBottom(pagetoc, pageTocElement) < 0) {
+                    pagetoc.scrollTop -= overflowBottom(pagetoc, pageTocElement);
+                }
+            }
+        }
+    }
+}
+
+if (document.getElementById("sidetoc") === null &&
+    document.getElementsByClassName("header").length > 0) {
+    // The sidetoc element doesn't exist yet, let's create it
+
+    // Create the empty sidetoc and pagetoc elements
+    const sidetoc = document.createElement("div");
+    const pagetoc = document.createElement("div");
+    sidetoc.id = "sidetoc";
+    pagetoc.id = "pagetoc";
+    sidetoc.appendChild(pagetoc);
+
+    // And append them to the current DOM
+    const main = document.querySelector('main');
+    main.insertBefore(sidetoc, main.firstChild);
+
+    // Populate sidebar on load
+    window.addEventListener("load", () => {
+        for (const header of document.getElementsByClassName("header")) {
+            const link = document.createElement("a");
+            link.innerHTML = header.innerHTML;
+            link.href = header.hash;
+            link.classList.add("pagetoc-" + header.parentElement.tagName);
+            document.getElementById("pagetoc").appendChild(link);
+            link.onclick = () => updatePageToc(link);
+        }
+        updatePageToc();
+    });
+
+    // Update page table of contents selected heading on scroll
+    window.addEventListener("scroll", () => updatePageToc());
+}

From 65589ad33f544003e49cabeb0b76f6b1f0d3ce30 Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <hopsi@tuta.io>
Date: Mon, 28 Jul 2025 11:45:21 +0200
Subject: [PATCH 2/5] remove the markers

---
 src/doc/rustc-dev-guide/src/asm.md                              | 2 --
 src/doc/rustc-dev-guide/src/backend/backend-agnostic.md         | 2 --
 src/doc/rustc-dev-guide/src/backend/implicit-caller-location.md | 2 --
 src/doc/rustc-dev-guide/src/backend/monomorph.md                | 2 --
 src/doc/rustc-dev-guide/src/backend/updating-llvm.md            | 2 --
 .../src/borrow_check/moves_and_initialization/move_paths.md     | 2 --
 src/doc/rustc-dev-guide/src/borrow_check/region_inference.md    | 2 --
 .../src/borrow_check/region_inference/constraint_propagation.md | 2 --
 .../src/borrow_check/region_inference/lifetime_parameters.md    | 2 --
 .../src/borrow_check/region_inference/member_constraints.md     | 2 --
 .../borrow_check/region_inference/placeholders_and_universes.md | 2 --
 src/doc/rustc-dev-guide/src/bug-fix-procedure.md                | 2 --
 .../src/building/bootstrapping/what-bootstrapping-does.md       | 2 --
 src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md    | 2 --
 src/doc/rustc-dev-guide/src/building/new-target.md              | 2 --
 src/doc/rustc-dev-guide/src/building/optimized-build.md         | 2 --
 src/doc/rustc-dev-guide/src/building/suggested.md               | 2 --
 src/doc/rustc-dev-guide/src/compiler-debugging.md               | 2 --
 src/doc/rustc-dev-guide/src/compiler-src.md                     | 2 --
 src/doc/rustc-dev-guide/src/const-eval/interpret.md             | 2 --
 src/doc/rustc-dev-guide/src/contributing.md                     | 2 --
 src/doc/rustc-dev-guide/src/coroutine-closures.md               | 2 --
 src/doc/rustc-dev-guide/src/debugging-support-in-rustc.md       | 2 --
 src/doc/rustc-dev-guide/src/diagnostics.md                      | 2 --
 src/doc/rustc-dev-guide/src/early_late_parameters.md            | 2 --
 src/doc/rustc-dev-guide/src/getting-started.md                  | 2 --
 src/doc/rustc-dev-guide/src/git.md                              | 2 --
 src/doc/rustc-dev-guide/src/guides/editions.md                  | 2 --
 src/doc/rustc-dev-guide/src/hir.md                              | 2 --
 src/doc/rustc-dev-guide/src/implementing_new_features.md        | 2 --
 src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md    | 2 --
 src/doc/rustc-dev-guide/src/macro-expansion.md                  | 2 --
 src/doc/rustc-dev-guide/src/mir/construction.md                 | 2 --
 src/doc/rustc-dev-guide/src/mir/dataflow.md                     | 2 --
 src/doc/rustc-dev-guide/src/mir/drop-elaboration.md             | 2 --
 src/doc/rustc-dev-guide/src/mir/index.md                        | 2 --
 src/doc/rustc-dev-guide/src/name-resolution.md                  | 2 --
 src/doc/rustc-dev-guide/src/normalization.md                    | 2 --
 src/doc/rustc-dev-guide/src/overview.md                         | 2 --
 src/doc/rustc-dev-guide/src/panic-implementation.md             | 2 --
 src/doc/rustc-dev-guide/src/profile-guided-optimization.md      | 2 --
 .../src/queries/incremental-compilation-in-detail.md            | 2 --
 src/doc/rustc-dev-guide/src/queries/incremental-compilation.md  | 2 --
 .../src/queries/query-evaluation-model-in-detail.md             | 2 --
 src/doc/rustc-dev-guide/src/queries/salsa.md                    | 2 --
 src/doc/rustc-dev-guide/src/query.md                            | 2 --
 src/doc/rustc-dev-guide/src/rustdoc-internals.md                | 2 --
 src/doc/rustc-dev-guide/src/rustdoc-internals/search.md         | 2 --
 src/doc/rustc-dev-guide/src/rustdoc.md                          | 2 --
 src/doc/rustc-dev-guide/src/stability.md                        | 2 --
 src/doc/rustc-dev-guide/src/stabilization_guide.md              | 2 --
 src/doc/rustc-dev-guide/src/test-implementation.md              | 2 --
 src/doc/rustc-dev-guide/src/tests/adding.md                     | 2 --
 src/doc/rustc-dev-guide/src/tests/compiletest.md                | 2 --
 src/doc/rustc-dev-guide/src/tests/directives.md                 | 2 --
 src/doc/rustc-dev-guide/src/tests/intro.md                      | 2 --
 src/doc/rustc-dev-guide/src/tests/running.md                    | 2 --
 src/doc/rustc-dev-guide/src/tests/ui.md                         | 2 --
 src/doc/rustc-dev-guide/src/thir.md                             | 2 --
 src/doc/rustc-dev-guide/src/tracing.md                          | 2 --
 src/doc/rustc-dev-guide/src/traits/goals-and-clauses.md         | 2 --
 src/doc/rustc-dev-guide/src/traits/lowering-to-logic.md         | 2 --
 src/doc/rustc-dev-guide/src/traits/resolution.md                | 2 --
 src/doc/rustc-dev-guide/src/ty.md                               | 2 --
 src/doc/rustc-dev-guide/src/type-inference.md                   | 2 --
 src/doc/rustc-dev-guide/src/typing_parameter_envs.md            | 2 --
 src/doc/rustc-dev-guide/src/variance.md                         | 2 --
 src/doc/rustc-dev-guide/src/walkthrough.md                      | 2 --
 68 files changed, 136 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/asm.md b/src/doc/rustc-dev-guide/src/asm.md
index 1bb493e73d584..b5857d5465e15 100644
--- a/src/doc/rustc-dev-guide/src/asm.md
+++ b/src/doc/rustc-dev-guide/src/asm.md
@@ -1,7 +1,5 @@
 # Inline assembly
 
-<!-- toc -->
-
 ## Overview
 
 Inline assembly in rustc mostly revolves around taking an `asm!` macro invocation and plumbing it
diff --git a/src/doc/rustc-dev-guide/src/backend/backend-agnostic.md b/src/doc/rustc-dev-guide/src/backend/backend-agnostic.md
index 0f81d3cb48a1d..2fdda4eda99a3 100644
--- a/src/doc/rustc-dev-guide/src/backend/backend-agnostic.md
+++ b/src/doc/rustc-dev-guide/src/backend/backend-agnostic.md
@@ -1,7 +1,5 @@
 # Backend Agnostic Codegen
 
-<!-- toc -->
-
 [`rustc_codegen_ssa`]
 provides an abstract interface for all backends to implement,
 namely LLVM, [Cranelift], and [GCC].
diff --git a/src/doc/rustc-dev-guide/src/backend/implicit-caller-location.md b/src/doc/rustc-dev-guide/src/backend/implicit-caller-location.md
index c5ee00813a344..9ca4bcab078e0 100644
--- a/src/doc/rustc-dev-guide/src/backend/implicit-caller-location.md
+++ b/src/doc/rustc-dev-guide/src/backend/implicit-caller-location.md
@@ -1,7 +1,5 @@
 # Implicit caller location
 
-<!-- toc -->
-
 Approved in [RFC 2091], this feature enables the accurate reporting of caller location during panics
 initiated from functions like `Option::unwrap`, `Result::expect`, and `Index::index`. This feature
 adds the [`#[track_caller]`][attr-reference] attribute for functions, the
diff --git a/src/doc/rustc-dev-guide/src/backend/monomorph.md b/src/doc/rustc-dev-guide/src/backend/monomorph.md
index 7ebb4d2b1e81c..e9d98597ee0d9 100644
--- a/src/doc/rustc-dev-guide/src/backend/monomorph.md
+++ b/src/doc/rustc-dev-guide/src/backend/monomorph.md
@@ -1,7 +1,5 @@
 # Monomorphization
 
-<!-- toc -->
-
 As you probably know, Rust has a very expressive type system that has extensive
 support for generic types. But of course, assembly is not generic, so we need
 to figure out the concrete types of all the generics before the code can
diff --git a/src/doc/rustc-dev-guide/src/backend/updating-llvm.md b/src/doc/rustc-dev-guide/src/backend/updating-llvm.md
index 18c822aad790e..ebef15d40baf5 100644
--- a/src/doc/rustc-dev-guide/src/backend/updating-llvm.md
+++ b/src/doc/rustc-dev-guide/src/backend/updating-llvm.md
@@ -1,7 +1,5 @@
 # Updating LLVM
 
-<!-- toc -->
-
 <!-- date-check: Aug 2024 -->
 Rust supports building against multiple LLVM versions:
 
diff --git a/src/doc/rustc-dev-guide/src/borrow_check/moves_and_initialization/move_paths.md b/src/doc/rustc-dev-guide/src/borrow_check/moves_and_initialization/move_paths.md
index ad9c75d629607..95518fbc0184f 100644
--- a/src/doc/rustc-dev-guide/src/borrow_check/moves_and_initialization/move_paths.md
+++ b/src/doc/rustc-dev-guide/src/borrow_check/moves_and_initialization/move_paths.md
@@ -1,7 +1,5 @@
 # Move paths
 
-<!-- toc -->
-
 In reality, it's not enough to track initialization at the granularity
 of local variables. Rust also allows us to do moves and initialization
 at the field granularity:
diff --git a/src/doc/rustc-dev-guide/src/borrow_check/region_inference.md b/src/doc/rustc-dev-guide/src/borrow_check/region_inference.md
index 85e71b4fa4298..0d55ab955836e 100644
--- a/src/doc/rustc-dev-guide/src/borrow_check/region_inference.md
+++ b/src/doc/rustc-dev-guide/src/borrow_check/region_inference.md
@@ -1,7 +1,5 @@
 # Region inference (NLL)
 
-<!-- toc -->
-
 The MIR-based region checking code is located in [the `rustc_mir::borrow_check`
 module][nll].
 
diff --git a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/constraint_propagation.md b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/constraint_propagation.md
index 4c30d25e0406f..c3f8c03cb29f5 100644
--- a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/constraint_propagation.md
+++ b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/constraint_propagation.md
@@ -1,7 +1,5 @@
 # Constraint propagation
 
-<!-- toc -->
-
 The main work of the region inference is **constraint propagation**,
 which is done in the [`propagate_constraints`] function.  There are
 three sorts of constraints that are used in NLL, and we'll explain how
diff --git a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/lifetime_parameters.md b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/lifetime_parameters.md
index fadfac4045696..2d337dbc020f6 100644
--- a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/lifetime_parameters.md
+++ b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/lifetime_parameters.md
@@ -1,7 +1,5 @@
 # Universal regions
 
-<!-- toc -->
-
 "Universal regions" is the name that the code uses to refer to "named
 lifetimes" -- e.g., lifetime parameters and `'static`. The name
 derives from the fact that such lifetimes are "universally quantified"
diff --git a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/member_constraints.md b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/member_constraints.md
index fd7c87ffcea7b..2804c97724f5a 100644
--- a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/member_constraints.md
+++ b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/member_constraints.md
@@ -1,7 +1,5 @@
 # Member constraints
 
-<!-- toc -->
-
 A member constraint `'m member of ['c_1..'c_N]` expresses that the
 region `'m` must be *equal* to some **choice regions** `'c_i` (for
 some `i`). These constraints cannot be expressed by users, but they
diff --git a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/placeholders_and_universes.md b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/placeholders_and_universes.md
index 91c8c45261191..11fd2a5fc7db8 100644
--- a/src/doc/rustc-dev-guide/src/borrow_check/region_inference/placeholders_and_universes.md
+++ b/src/doc/rustc-dev-guide/src/borrow_check/region_inference/placeholders_and_universes.md
@@ -1,7 +1,5 @@
 # Placeholders and universes
 
-<!-- toc -->
-
 From time to time we have to reason about regions that we can't
 concretely know. For example, consider this program:
 
diff --git a/src/doc/rustc-dev-guide/src/bug-fix-procedure.md b/src/doc/rustc-dev-guide/src/bug-fix-procedure.md
index 55436261fdefa..6b13c97023f54 100644
--- a/src/doc/rustc-dev-guide/src/bug-fix-procedure.md
+++ b/src/doc/rustc-dev-guide/src/bug-fix-procedure.md
@@ -1,7 +1,5 @@
 # Procedures for breaking changes
 
-<!-- toc -->
-
 This page defines the best practices procedure for making bug fixes or soundness
 corrections in the compiler that can cause existing code to stop compiling. This
 text is based on
diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping/what-bootstrapping-does.md b/src/doc/rustc-dev-guide/src/building/bootstrapping/what-bootstrapping-does.md
index 2793ad4381526..da425d8d39bba 100644
--- a/src/doc/rustc-dev-guide/src/building/bootstrapping/what-bootstrapping-does.md
+++ b/src/doc/rustc-dev-guide/src/building/bootstrapping/what-bootstrapping-does.md
@@ -1,7 +1,5 @@
 # What Bootstrapping does
 
-<!-- toc -->
-
 [*Bootstrapping*][boot] is the process of using a compiler to compile itself.
 More accurately, it means using an older compiler to compile a newer version of
 the same compiler.
diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
index d29cd14481025..b07d3533f59bc 100644
--- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
+++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
@@ -1,7 +1,5 @@
 # How to build and run the compiler
 
-<!-- toc -->
-
 <div class="warning">
 
 For `profile = "library"` users, or users who use `download-rustc = true | "if-unchanged"`, please be advised that
diff --git a/src/doc/rustc-dev-guide/src/building/new-target.md b/src/doc/rustc-dev-guide/src/building/new-target.md
index e11a2cd8ee577..436aec8ee265b 100644
--- a/src/doc/rustc-dev-guide/src/building/new-target.md
+++ b/src/doc/rustc-dev-guide/src/building/new-target.md
@@ -6,8 +6,6 @@ relevant to your desired goal.
 
 See also the associated documentation in the [target tier policy].
 
-<!-- toc -->
-
 [target tier policy]: https://doc.rust-lang.org/rustc/target-tier-policy.html#adding-a-new-target
 
 ## Specifying a new LLVM
diff --git a/src/doc/rustc-dev-guide/src/building/optimized-build.md b/src/doc/rustc-dev-guide/src/building/optimized-build.md
index 62dfaca89d24e..863ed9749fb7e 100644
--- a/src/doc/rustc-dev-guide/src/building/optimized-build.md
+++ b/src/doc/rustc-dev-guide/src/building/optimized-build.md
@@ -1,7 +1,5 @@
 # Optimized build of the compiler
 
-<!-- toc -->
-
 There are multiple additional build configuration options and techniques that can be used to compile a
 build of `rustc` that is as optimized as possible (for example when building `rustc` for a Linux
 distribution). The status of these configuration options for various Rust targets is tracked [here].
diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md
index c046161e77f25..35c7e935b5688 100644
--- a/src/doc/rustc-dev-guide/src/building/suggested.md
+++ b/src/doc/rustc-dev-guide/src/building/suggested.md
@@ -3,8 +3,6 @@
 The full bootstrapping process takes quite a while. Here are some suggestions to
 make your life easier.
 
-<!-- toc -->
-
 ## Installing a pre-push hook
 
 CI will automatically fail your build if it doesn't pass `tidy`, our internal
diff --git a/src/doc/rustc-dev-guide/src/compiler-debugging.md b/src/doc/rustc-dev-guide/src/compiler-debugging.md
index 102e20207792e..edd2aa6c5f64b 100644
--- a/src/doc/rustc-dev-guide/src/compiler-debugging.md
+++ b/src/doc/rustc-dev-guide/src/compiler-debugging.md
@@ -1,7 +1,5 @@
 # Debugging the compiler
 
-<!-- toc -->
-
 This chapter contains a few tips to debug the compiler. These tips aim to be
 useful no matter what you are working on.  Some of the other chapters have
 advice about specific parts of the compiler (e.g. the [Queries Debugging and
diff --git a/src/doc/rustc-dev-guide/src/compiler-src.md b/src/doc/rustc-dev-guide/src/compiler-src.md
index 00aa96226849d..d67bacb1b3395 100644
--- a/src/doc/rustc-dev-guide/src/compiler-src.md
+++ b/src/doc/rustc-dev-guide/src/compiler-src.md
@@ -1,7 +1,5 @@
 # High-level overview of the compiler source
 
-<!-- toc -->
-
 Now that we have [seen what the compiler does][orgch],
 let's take a look at the structure of the [`rust-lang/rust`] repository,
 where the rustc source code lives.
diff --git a/src/doc/rustc-dev-guide/src/const-eval/interpret.md b/src/doc/rustc-dev-guide/src/const-eval/interpret.md
index 51a539de5cb6e..08382b12ff00a 100644
--- a/src/doc/rustc-dev-guide/src/const-eval/interpret.md
+++ b/src/doc/rustc-dev-guide/src/const-eval/interpret.md
@@ -1,7 +1,5 @@
 # Interpreter
 
-<!-- toc -->
-
 The interpreter is a virtual machine for executing MIR without compiling to
 machine code. It is usually invoked via `tcx.const_eval_*` functions. The
 interpreter is shared between the compiler (for compile-time function
diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md
index b3fcd79ec8184..963bef3af8de3 100644
--- a/src/doc/rustc-dev-guide/src/contributing.md
+++ b/src/doc/rustc-dev-guide/src/contributing.md
@@ -1,7 +1,5 @@
 # Contribution procedures
 
-<!-- toc -->
-
 ## Bug reports
 
 While bugs are unfortunate, they're a reality in software. We can't fix what we
diff --git a/src/doc/rustc-dev-guide/src/coroutine-closures.md b/src/doc/rustc-dev-guide/src/coroutine-closures.md
index 48cdba44a9f52..2617c824a3911 100644
--- a/src/doc/rustc-dev-guide/src/coroutine-closures.md
+++ b/src/doc/rustc-dev-guide/src/coroutine-closures.md
@@ -1,7 +1,5 @@
 # Async closures/"coroutine-closures"
 
-<!-- toc -->
-
 Please read [RFC 3668](https://rust-lang.github.io/rfcs/3668-async-closures.html) to understand the general motivation of the feature. This is a very technical and somewhat "vertical" chapter; ideally we'd split this and sprinkle it across all the relevant chapters, but for the purposes of understanding async closures *holistically*, I've put this together all here in one chapter.
 
 ## Coroutine-closures -- a technical deep dive
diff --git a/src/doc/rustc-dev-guide/src/debugging-support-in-rustc.md b/src/doc/rustc-dev-guide/src/debugging-support-in-rustc.md
index ac629934e0a42..bd4f795ce03b6 100644
--- a/src/doc/rustc-dev-guide/src/debugging-support-in-rustc.md
+++ b/src/doc/rustc-dev-guide/src/debugging-support-in-rustc.md
@@ -1,7 +1,5 @@
 # Debugging support in the Rust compiler
 
-<!-- toc -->
-
 This document explains the state of debugging tools support in the Rust compiler (rustc).
 It gives an overview of GDB, LLDB, WinDbg/CDB,
 as well as infrastructure around Rust compiler to debug Rust code.
diff --git a/src/doc/rustc-dev-guide/src/diagnostics.md b/src/doc/rustc-dev-guide/src/diagnostics.md
index 33f5441d36e4f..82191e0a6eaf4 100644
--- a/src/doc/rustc-dev-guide/src/diagnostics.md
+++ b/src/doc/rustc-dev-guide/src/diagnostics.md
@@ -1,7 +1,5 @@
 # Errors and lints
 
-<!-- toc -->
-
 A lot of effort has been put into making `rustc` have great error messages.
 This chapter is about how to emit compile errors and lints from the compiler.
 
diff --git a/src/doc/rustc-dev-guide/src/early_late_parameters.md b/src/doc/rustc-dev-guide/src/early_late_parameters.md
index 3f94b09056684..c472bdc2c4812 100644
--- a/src/doc/rustc-dev-guide/src/early_late_parameters.md
+++ b/src/doc/rustc-dev-guide/src/early_late_parameters.md
@@ -1,8 +1,6 @@
 
 # Early vs Late bound parameters
 
-<!-- toc -->
-
 > **NOTE**: This chapter largely talks about early/late bound as being solely relevant when discussing function item types/function definitions. This is potentially not completely true, async blocks and closures should likely be discussed somewhat in this chapter.
 
 ## What does it mean to be "early" bound or "late" bound
diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md
index d6c5c3ac8521b..04d2e37732fa9 100644
--- a/src/doc/rustc-dev-guide/src/getting-started.md
+++ b/src/doc/rustc-dev-guide/src/getting-started.md
@@ -3,8 +3,6 @@
 Thank you for your interest in contributing to Rust! There are many ways to
 contribute, and we appreciate all of them.
 
-<!-- toc -->
-
 If this is your first time contributing, the [walkthrough] chapter can give you a good example of
 how a typical contribution would go.
 
diff --git a/src/doc/rustc-dev-guide/src/git.md b/src/doc/rustc-dev-guide/src/git.md
index 8726ddfce20cc..447c6fd454671 100644
--- a/src/doc/rustc-dev-guide/src/git.md
+++ b/src/doc/rustc-dev-guide/src/git.md
@@ -1,7 +1,5 @@
 # Using Git
 
-<!-- toc -->
-
 The Rust project uses [Git] to manage its source code. In order to
 contribute, you'll need some familiarity with its features so that your changes
 can be incorporated into the compiler.
diff --git a/src/doc/rustc-dev-guide/src/guides/editions.md b/src/doc/rustc-dev-guide/src/guides/editions.md
index 9a92d4ebcb510..b65fbb13cd185 100644
--- a/src/doc/rustc-dev-guide/src/guides/editions.md
+++ b/src/doc/rustc-dev-guide/src/guides/editions.md
@@ -1,7 +1,5 @@
 # Editions
 
-<!-- toc -->
-
 This chapter gives an overview of how Edition support works in rustc.
 This assumes that you are familiar with what Editions are (see the [Edition Guide]).
 
diff --git a/src/doc/rustc-dev-guide/src/hir.md b/src/doc/rustc-dev-guide/src/hir.md
index 72fb10701574b..38ba33112f2ec 100644
--- a/src/doc/rustc-dev-guide/src/hir.md
+++ b/src/doc/rustc-dev-guide/src/hir.md
@@ -1,7 +1,5 @@
 # The HIR
 
-<!-- toc -->
-
 The HIR – "High-Level Intermediate Representation" – is the primary IR used
 in most of rustc. It is a compiler-friendly representation of the abstract
 syntax tree (AST) that is generated after parsing, macro expansion, and name
diff --git a/src/doc/rustc-dev-guide/src/implementing_new_features.md b/src/doc/rustc-dev-guide/src/implementing_new_features.md
index 76cf2386c826a..00bce8599e430 100644
--- a/src/doc/rustc-dev-guide/src/implementing_new_features.md
+++ b/src/doc/rustc-dev-guide/src/implementing_new_features.md
@@ -1,7 +1,5 @@
 # Implementing new language features
 
-<!-- toc -->
-
 When you want to implement a new significant feature in the compiler, you need to go through this process to make sure everything goes smoothly.
 
 **NOTE: This section is for *language* features, not *library* features, which use [a different process].**
diff --git a/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md b/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md
index 880363b94bf2b..288b90f33c3d2 100644
--- a/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md
+++ b/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md
@@ -1,7 +1,5 @@
 # LLVM source-based code coverage
 
-<!-- toc -->
-
 `rustc` supports detailed source-based code and test coverage analysis
 with a command line option (`-C instrument-coverage`) that instruments Rust
 libraries and binaries with additional instructions and data, at compile time.
diff --git a/src/doc/rustc-dev-guide/src/macro-expansion.md b/src/doc/rustc-dev-guide/src/macro-expansion.md
index a90f717004f0b..54d6d2b4e8138 100644
--- a/src/doc/rustc-dev-guide/src/macro-expansion.md
+++ b/src/doc/rustc-dev-guide/src/macro-expansion.md
@@ -1,7 +1,5 @@
 # Macro expansion
 
-<!-- toc -->
-
 Rust has a very powerful macro system. In the previous chapter, we saw how
 the parser sets aside macros to be expanded (using temporary [placeholders]).
 This chapter is about the process of expanding those macros iteratively until
diff --git a/src/doc/rustc-dev-guide/src/mir/construction.md b/src/doc/rustc-dev-guide/src/mir/construction.md
index f2559a22b9555..8360d9ff1a8bc 100644
--- a/src/doc/rustc-dev-guide/src/mir/construction.md
+++ b/src/doc/rustc-dev-guide/src/mir/construction.md
@@ -1,7 +1,5 @@
 # MIR construction
 
-<!-- toc -->
-
 The lowering of [HIR] to [MIR] occurs for the following (probably incomplete)
 list of items:
 
diff --git a/src/doc/rustc-dev-guide/src/mir/dataflow.md b/src/doc/rustc-dev-guide/src/mir/dataflow.md
index 85e57dd839b81..970e61196c122 100644
--- a/src/doc/rustc-dev-guide/src/mir/dataflow.md
+++ b/src/doc/rustc-dev-guide/src/mir/dataflow.md
@@ -1,7 +1,5 @@
 # Dataflow Analysis
 
-<!-- toc -->
-
 If you work on the MIR, you will frequently come across various flavors of
 [dataflow analysis][wiki]. `rustc` uses dataflow to find uninitialized
 variables, determine what variables are live across a generator `yield`
diff --git a/src/doc/rustc-dev-guide/src/mir/drop-elaboration.md b/src/doc/rustc-dev-guide/src/mir/drop-elaboration.md
index 3b321fd44d1d3..4da612c83f0fc 100644
--- a/src/doc/rustc-dev-guide/src/mir/drop-elaboration.md
+++ b/src/doc/rustc-dev-guide/src/mir/drop-elaboration.md
@@ -1,7 +1,5 @@
 # Drop elaboration
 
-<!-- toc -->
-
 ## Dynamic drops
 
 According to the [reference][reference-drop]:
diff --git a/src/doc/rustc-dev-guide/src/mir/index.md b/src/doc/rustc-dev-guide/src/mir/index.md
index f355875aa156e..8ba5f3ac8b784 100644
--- a/src/doc/rustc-dev-guide/src/mir/index.md
+++ b/src/doc/rustc-dev-guide/src/mir/index.md
@@ -1,7 +1,5 @@
 # The MIR (Mid-level IR)
 
-<!-- toc -->
-
 MIR is Rust's _Mid-level Intermediate Representation_. It is
 constructed from [HIR](../hir.html). MIR was introduced in
 [RFC 1211]. It is a radically simplified form of Rust that is used for
diff --git a/src/doc/rustc-dev-guide/src/name-resolution.md b/src/doc/rustc-dev-guide/src/name-resolution.md
index 719ebce855366..2e96382f77970 100644
--- a/src/doc/rustc-dev-guide/src/name-resolution.md
+++ b/src/doc/rustc-dev-guide/src/name-resolution.md
@@ -1,7 +1,5 @@
 # Name resolution
 
-<!-- toc -->
-
 In the previous chapters, we saw how the [*Abstract Syntax Tree* (`AST`)][ast]
 is built with all macros expanded. We saw how doing that requires doing some
 name resolution to resolve imports and macro names. In this chapter, we show
diff --git a/src/doc/rustc-dev-guide/src/normalization.md b/src/doc/rustc-dev-guide/src/normalization.md
index eb0962a412237..53e20f1c0db7f 100644
--- a/src/doc/rustc-dev-guide/src/normalization.md
+++ b/src/doc/rustc-dev-guide/src/normalization.md
@@ -1,7 +1,5 @@
 # Aliases and Normalization
 
-<!-- toc -->
-
 ## Aliases
 
 In Rust there are a number of types that are considered equal to some "underlying" type, for example inherent associated types, trait associated types, free type aliases (`type Foo = u32`), and opaque types (`-> impl RPIT`). We consider such types to be "aliases", alias types are represented by the [`TyKind::Alias`][tykind_alias] variant, with the kind of alias tracked by the [`AliasTyKind`][aliaskind] enum.
diff --git a/src/doc/rustc-dev-guide/src/overview.md b/src/doc/rustc-dev-guide/src/overview.md
index 8a1a22fad660a..12b76828b5c3b 100644
--- a/src/doc/rustc-dev-guide/src/overview.md
+++ b/src/doc/rustc-dev-guide/src/overview.md
@@ -1,7 +1,5 @@
 # Overview of the compiler
 
-<!-- toc -->
-
 This chapter is about the overall process of compiling a program -- how
 everything fits together.
 
diff --git a/src/doc/rustc-dev-guide/src/panic-implementation.md b/src/doc/rustc-dev-guide/src/panic-implementation.md
index 468190ffccd50..dba3f2146d23d 100644
--- a/src/doc/rustc-dev-guide/src/panic-implementation.md
+++ b/src/doc/rustc-dev-guide/src/panic-implementation.md
@@ -1,7 +1,5 @@
 # Panicking in Rust
 
-<!-- toc -->
-
 ## Step 1: Invocation of the `panic!` macro.
 
 There are actually two panic macros - one defined in `core`, and one defined in `std`.
diff --git a/src/doc/rustc-dev-guide/src/profile-guided-optimization.md b/src/doc/rustc-dev-guide/src/profile-guided-optimization.md
index 2fa8102104513..4e3dadd406ec0 100644
--- a/src/doc/rustc-dev-guide/src/profile-guided-optimization.md
+++ b/src/doc/rustc-dev-guide/src/profile-guided-optimization.md
@@ -1,7 +1,5 @@
 # Profile-guided optimization
 
-<!-- toc -->
-
 `rustc` supports doing profile-guided optimization (PGO).
 This chapter describes what PGO is and how the support for it is
 implemented in `rustc`.
diff --git a/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md b/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md
index 18e0e25c53152..46e38832e64d2 100644
--- a/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md
+++ b/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md
@@ -1,7 +1,5 @@
 # Incremental compilation in detail
 
-<!-- toc -->
-
 The incremental compilation scheme is, in essence, a surprisingly
 simple extension to the overall query system. It relies on the fact that:
 
diff --git a/src/doc/rustc-dev-guide/src/queries/incremental-compilation.md b/src/doc/rustc-dev-guide/src/queries/incremental-compilation.md
index 6e5b4e8cc4992..731ff3287d9fe 100644
--- a/src/doc/rustc-dev-guide/src/queries/incremental-compilation.md
+++ b/src/doc/rustc-dev-guide/src/queries/incremental-compilation.md
@@ -1,7 +1,5 @@
 # Incremental compilation
 
-<!-- toc -->
-
 The incremental compilation scheme is, in essence, a surprisingly
 simple extension to the overall query system. We'll start by describing
 a slightly simplified variant of the real thing – the "basic algorithm" –
diff --git a/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md b/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md
index 444e20bc580e3..c1a4373f7dac6 100644
--- a/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md
+++ b/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md
@@ -1,7 +1,5 @@
 # The Query Evaluation Model in detail
 
-<!-- toc -->
-
 This chapter provides a deeper dive into the abstract model queries are built on.
 It does not go into implementation details but tries to explain
 the underlying logic. The examples here, therefore, have been stripped down and
diff --git a/src/doc/rustc-dev-guide/src/queries/salsa.md b/src/doc/rustc-dev-guide/src/queries/salsa.md
index 1a7b7fa9a6832..dc7160edc22cd 100644
--- a/src/doc/rustc-dev-guide/src/queries/salsa.md
+++ b/src/doc/rustc-dev-guide/src/queries/salsa.md
@@ -1,7 +1,5 @@
 # How Salsa works
 
-<!-- toc -->
-
 This chapter is based on the explanation given by Niko Matsakis in this
 [video](https://www.youtube.com/watch?v=_muY4HjSqVw) about
 [Salsa](https://github.com/salsa-rs/salsa). To find out more you may
diff --git a/src/doc/rustc-dev-guide/src/query.md b/src/doc/rustc-dev-guide/src/query.md
index 0ca1b360a7014..8377a7b2f31a7 100644
--- a/src/doc/rustc-dev-guide/src/query.md
+++ b/src/doc/rustc-dev-guide/src/query.md
@@ -1,7 +1,5 @@
 # Queries: demand-driven compilation
 
-<!-- toc -->
-
 As described in [Overview of the compiler], the Rust compiler
 is still (as of <!-- date-check --> July 2021) transitioning from a
 traditional "pass-based" setup to a "demand-driven" system. The compiler query
diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals.md b/src/doc/rustc-dev-guide/src/rustdoc-internals.md
index 0234d4a920ed8..4affbafe4777a 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals.md
@@ -1,7 +1,5 @@
 # Rustdoc Internals
 
-<!-- toc -->
-
 This page describes [`rustdoc`]'s passes and modes. For an overview of `rustdoc`,
 see the ["Rustdoc overview" chapter](./rustdoc.md).
 
diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/search.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/search.md
index 3506431118baf..beff0a94c1ecd 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals/search.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/search.md
@@ -7,8 +7,6 @@ in the crates in the doc bundle, and the second reads
 it, turns it into some in-memory structures, and
 scans them linearly to search.
 
-<!-- toc -->
-
 ## Search index format
 
 `search.js` calls this Raw, because it turns it into
diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md
index 52ae48c3735c0..9290fcd3b41cb 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc.md
@@ -9,8 +9,6 @@ For more details about how rustdoc works, see the
 
 [Rustdoc internals]: ./rustdoc-internals.md
 
-<!-- toc -->
-
 `rustdoc` uses `rustc` internals (and, of course, the standard library), so you
 will have to build the compiler and `std` once before you can build `rustdoc`.
 
diff --git a/src/doc/rustc-dev-guide/src/stability.md b/src/doc/rustc-dev-guide/src/stability.md
index 230925252bac3..d0cee54adb6a0 100644
--- a/src/doc/rustc-dev-guide/src/stability.md
+++ b/src/doc/rustc-dev-guide/src/stability.md
@@ -6,8 +6,6 @@ APIs to use unstable APIs internally in the rustc standard library.
 **NOTE**: this section is for *library* features, not *language* features. For instructions on
 stabilizing a language feature see [Stabilizing Features](./stabilization_guide.md).
 
-<!-- toc -->
-
 ## unstable
 
 The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]`
diff --git a/src/doc/rustc-dev-guide/src/stabilization_guide.md b/src/doc/rustc-dev-guide/src/stabilization_guide.md
index f155272e5a2c6..e399930fc523d 100644
--- a/src/doc/rustc-dev-guide/src/stabilization_guide.md
+++ b/src/doc/rustc-dev-guide/src/stabilization_guide.md
@@ -6,8 +6,6 @@
 
 Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization, though involving the people who have worked on it is prudent. Follow these steps:
 
-<!-- toc -->
-
 ## Write an RFC, if needed
 
 If the feature was part of a [lang experiment], the lang team generally will want to first accept an RFC before stabilization.
diff --git a/src/doc/rustc-dev-guide/src/test-implementation.md b/src/doc/rustc-dev-guide/src/test-implementation.md
index e906dd29f25f5..f09d73631998f 100644
--- a/src/doc/rustc-dev-guide/src/test-implementation.md
+++ b/src/doc/rustc-dev-guide/src/test-implementation.md
@@ -1,7 +1,5 @@
 # The `#[test]` attribute
 
-<!-- toc -->
-
 
 
 Many Rust programmers rely on a built-in attribute called `#[test]`. All
diff --git a/src/doc/rustc-dev-guide/src/tests/adding.md b/src/doc/rustc-dev-guide/src/tests/adding.md
index 895eabfbd56a7..e5c26bef11d0c 100644
--- a/src/doc/rustc-dev-guide/src/tests/adding.md
+++ b/src/doc/rustc-dev-guide/src/tests/adding.md
@@ -1,7 +1,5 @@
 # Adding new tests
 
-<!-- toc -->
-
 **In general, we expect every PR that fixes a bug in rustc to come accompanied
 by a regression test of some kind.** This test should fail in master but pass
 after the PR. These tests are really useful for preventing us from repeating the
diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md
index a108dfdef9b3f..4980ed845d6dd 100644
--- a/src/doc/rustc-dev-guide/src/tests/compiletest.md
+++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md
@@ -1,7 +1,5 @@
 # Compiletest
 
-<!-- toc -->
-
 ## Introduction
 
 `compiletest` is the main test harness of the Rust test suite. It allows test
diff --git a/src/doc/rustc-dev-guide/src/tests/directives.md b/src/doc/rustc-dev-guide/src/tests/directives.md
index 5c3ae359ba0bf..a16be9b482553 100644
--- a/src/doc/rustc-dev-guide/src/tests/directives.md
+++ b/src/doc/rustc-dev-guide/src/tests/directives.md
@@ -1,7 +1,5 @@
 # Compiletest directives
 
-<!-- toc -->
-
 <!--
 FIXME(jieyouxu) completely revise this chapter.
 -->
diff --git a/src/doc/rustc-dev-guide/src/tests/intro.md b/src/doc/rustc-dev-guide/src/tests/intro.md
index 79b96c450a8d8..b90c16d602c31 100644
--- a/src/doc/rustc-dev-guide/src/tests/intro.md
+++ b/src/doc/rustc-dev-guide/src/tests/intro.md
@@ -1,7 +1,5 @@
 # Testing the compiler
 
-<!-- toc -->
-
 The Rust project runs a wide variety of different tests, orchestrated by the
 build system (`./x test`). This section gives a brief overview of the different
 testing tools. Subsequent chapters dive into [running tests](running.md) and
diff --git a/src/doc/rustc-dev-guide/src/tests/running.md b/src/doc/rustc-dev-guide/src/tests/running.md
index 6526fe9c2357a..f6e313062cda8 100644
--- a/src/doc/rustc-dev-guide/src/tests/running.md
+++ b/src/doc/rustc-dev-guide/src/tests/running.md
@@ -1,7 +1,5 @@
 # Running tests
 
-<!-- toc -->
-
 You can run the entire test collection using `x`. But note that running the
 *entire* test collection is almost never what you want to do during local
 development because it takes a really long time. For local development, see the
diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md
index 782f78d76148e..c1e67e1b755c5 100644
--- a/src/doc/rustc-dev-guide/src/tests/ui.md
+++ b/src/doc/rustc-dev-guide/src/tests/ui.md
@@ -1,7 +1,5 @@
 # UI tests
 
-<!-- toc -->
-
 UI tests are a particular [test suite](compiletest.md#test-suites) of
 compiletest.
 
diff --git a/src/doc/rustc-dev-guide/src/thir.md b/src/doc/rustc-dev-guide/src/thir.md
index 73d09ad80bf96..3d3dafaef49ba 100644
--- a/src/doc/rustc-dev-guide/src/thir.md
+++ b/src/doc/rustc-dev-guide/src/thir.md
@@ -1,7 +1,5 @@
 # The THIR
 
-<!-- toc -->
-
 The THIR ("Typed High-Level Intermediate Representation"), previously called HAIR for
 "High-Level Abstract IR", is another IR used by rustc that is generated after
 [type checking]. It is (as of <!-- date-check --> January 2024) used for
diff --git a/src/doc/rustc-dev-guide/src/tracing.md b/src/doc/rustc-dev-guide/src/tracing.md
index 0cfdf306e92d1..5e5b81fc65b22 100644
--- a/src/doc/rustc-dev-guide/src/tracing.md
+++ b/src/doc/rustc-dev-guide/src/tracing.md
@@ -1,7 +1,5 @@
 # Using tracing to debug the compiler
 
-<!-- toc -->
-
 The compiler has a lot of [`debug!`] (or `trace!`) calls, which print out logging information
 at many points. These are very useful to at least narrow down the location of
 a bug if not to find it entirely, or just to orient yourself as to why the
diff --git a/src/doc/rustc-dev-guide/src/traits/goals-and-clauses.md b/src/doc/rustc-dev-guide/src/traits/goals-and-clauses.md
index 40fd4581bf3e5..2884ca5a05a1f 100644
--- a/src/doc/rustc-dev-guide/src/traits/goals-and-clauses.md
+++ b/src/doc/rustc-dev-guide/src/traits/goals-and-clauses.md
@@ -1,7 +1,5 @@
 # Goals and clauses
 
-<!-- toc -->
-
 In logic programming terms, a **goal** is something that you must
 prove and a **clause** is something that you know is true. As
 described in the [lowering to logic](./lowering-to-logic.html)
diff --git a/src/doc/rustc-dev-guide/src/traits/lowering-to-logic.md b/src/doc/rustc-dev-guide/src/traits/lowering-to-logic.md
index 1248d434610b9..cc8b3bf800cb9 100644
--- a/src/doc/rustc-dev-guide/src/traits/lowering-to-logic.md
+++ b/src/doc/rustc-dev-guide/src/traits/lowering-to-logic.md
@@ -1,7 +1,5 @@
 # Lowering to logic
 
-<!-- toc -->
-
 The key observation here is that the Rust trait system is basically a
 kind of logic, and it can be mapped onto standard logical inference
 rules. We can then look for solutions to those inference rules in a
diff --git a/src/doc/rustc-dev-guide/src/traits/resolution.md b/src/doc/rustc-dev-guide/src/traits/resolution.md
index c62b0593694f1..ccb2b04268e85 100644
--- a/src/doc/rustc-dev-guide/src/traits/resolution.md
+++ b/src/doc/rustc-dev-guide/src/traits/resolution.md
@@ -1,7 +1,5 @@
 # Trait resolution (old-style)
 
-<!-- toc -->
-
 This chapter describes the general process of _trait resolution_ and points out
 some non-obvious things.
 
diff --git a/src/doc/rustc-dev-guide/src/ty.md b/src/doc/rustc-dev-guide/src/ty.md
index 767ac3fdba21b..4055f475e9923 100644
--- a/src/doc/rustc-dev-guide/src/ty.md
+++ b/src/doc/rustc-dev-guide/src/ty.md
@@ -1,7 +1,5 @@
 # The `ty` module: representing types
 
-<!-- toc -->
-
 The `ty` module defines how the Rust compiler represents types internally. It also defines the
 *typing context* (`tcx` or `TyCtxt`), which is the central data structure in the compiler.
 
diff --git a/src/doc/rustc-dev-guide/src/type-inference.md b/src/doc/rustc-dev-guide/src/type-inference.md
index 888eb2439c5bc..2243205f129b5 100644
--- a/src/doc/rustc-dev-guide/src/type-inference.md
+++ b/src/doc/rustc-dev-guide/src/type-inference.md
@@ -1,7 +1,5 @@
 # Type inference
 
-<!-- toc -->
-
 Type inference is the process of automatic detection of the type of an
 expression.
 
diff --git a/src/doc/rustc-dev-guide/src/typing_parameter_envs.md b/src/doc/rustc-dev-guide/src/typing_parameter_envs.md
index e21bc5155da15..db15467a47a06 100644
--- a/src/doc/rustc-dev-guide/src/typing_parameter_envs.md
+++ b/src/doc/rustc-dev-guide/src/typing_parameter_envs.md
@@ -1,7 +1,5 @@
 # Typing/Parameter Environments
 
-<!-- toc -->
-
 ## Typing Environments
 
 When interacting with the type system there are a few variables to consider that can affect the results of trait solving. The set of in-scope where clauses, and what phase of the compiler type system operations are being performed in (the [`ParamEnv`][penv] and [`TypingMode`][tmode] structs respectively).
diff --git a/src/doc/rustc-dev-guide/src/variance.md b/src/doc/rustc-dev-guide/src/variance.md
index ad4fa4adfddb9..7aa0140715517 100644
--- a/src/doc/rustc-dev-guide/src/variance.md
+++ b/src/doc/rustc-dev-guide/src/variance.md
@@ -1,7 +1,5 @@
 # Variance of type and lifetime parameters
 
-<!-- toc -->
-
 For a more general background on variance, see the [background] appendix.
 
 [background]: ./appendix/background.html
diff --git a/src/doc/rustc-dev-guide/src/walkthrough.md b/src/doc/rustc-dev-guide/src/walkthrough.md
index 48b3f8bb15d3b..b4c3379347ed2 100644
--- a/src/doc/rustc-dev-guide/src/walkthrough.md
+++ b/src/doc/rustc-dev-guide/src/walkthrough.md
@@ -1,7 +1,5 @@
 # Walkthrough: a typical contribution
 
-<!-- toc -->
-
 There are _a lot_ of ways to contribute to the Rust compiler, including fixing
 bugs, improving performance, helping design features, providing feedback on
 existing features, etc. This chapter does not claim to scratch the surface.

From 5ebb0dd7da0c1c0fe6c6505fc1387d8805fd8a6d Mon Sep 17 00:00:00 2001
From: Kivooeo <Kivooeo123@gmail.com>
Date: Sat, 2 Aug 2025 19:01:07 +0500
Subject: [PATCH 3/5] update doc

---
 src/doc/rustc-dev-guide/src/appendix/humorust.md | 2 +-
 src/doc/rustc-dev-guide/src/tests/directives.md  | 2 +-
 src/doc/rustc-dev-guide/src/tests/ui.md          | 8 +++-----
 3 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/src/doc/rustc-dev-guide/src/appendix/humorust.md b/src/doc/rustc-dev-guide/src/appendix/humorust.md
index 6df3b212aa77c..8681512ed56a9 100644
--- a/src/doc/rustc-dev-guide/src/appendix/humorust.md
+++ b/src/doc/rustc-dev-guide/src/appendix/humorust.md
@@ -3,7 +3,7 @@
 What's a project without a sense of humor? And frankly some of these are
 enlightening?
 
-- [Weird exprs test](https://github.com/rust-lang/rust/blob/master/tests/ui/weird-exprs.rs)
+- [Weird exprs test](https://github.com/rust-lang/rust/blob/master/tests/ui/expr/weird-exprs.rs)
 - [Ferris Rap](https://fitzgen.com/2018/12/13/rust-raps.html)
 - [The Genesis of Generic Germination](https://github.com/rust-lang/rust/pull/53645#issue-210543221)
 - [The Bastion of the Turbofish test](https://github.com/rust-lang/rust/blob/79d8a0fcefa5134db2a94739b1d18daa01fc6e9f/src/test/ui/bastion-of-the-turbofish.rs)
diff --git a/src/doc/rustc-dev-guide/src/tests/directives.md b/src/doc/rustc-dev-guide/src/tests/directives.md
index 6fff021b0b12b..bda95e4dfbcce 100644
--- a/src/doc/rustc-dev-guide/src/tests/directives.md
+++ b/src/doc/rustc-dev-guide/src/tests/directives.md
@@ -359,7 +359,7 @@ described below:
   - Example: `x86_64-unknown-linux-gnu`
 
 See
-[`tests/ui/commandline-argfile.rs`](https://github.com/rust-lang/rust/blob/master/tests/ui/argfile/commandline-argfile.rs)
+[`tests/ui/argfile/commandline-argfile.rs`](https://github.com/rust-lang/rust/blob/master/tests/ui/argfile/commandline-argfile.rs)
 for an example of a test that uses this substitution.
 
 [output normalization]: ui.md#normalization
diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md
index 782f78d76148e..eecd72695d959 100644
--- a/src/doc/rustc-dev-guide/src/tests/ui.md
+++ b/src/doc/rustc-dev-guide/src/tests/ui.md
@@ -25,9 +25,9 @@ If you need to work with `#![no_std]` cross-compiling tests, consult the
 
 ## General structure of a test
 
-A test consists of a Rust source file located anywhere in the `tests/ui`
-directory, but they should be placed in a suitable sub-directory. For example,
-[`tests/ui/hello.rs`] is a basic hello-world test.
+A test consists of a Rust source file located in the `tests/ui` directory.
+**Tests must be placed in the appropriate subdirectory** based on their purpose
+and testing category - placing tests directly in `tests/ui` is not permitted.
 
 Compiletest will use `rustc` to compile the test, and compare the output against
 the expected output which is stored in a `.stdout` or `.stderr` file located
@@ -46,8 +46,6 @@ pass/fail expectations](#controlling-passfail-expectations).
 By default, a test is built as an executable binary. If you need a different
 crate type, you can use the `#![crate_type]` attribute to set it as needed.
 
-[`tests/ui/hello.rs`]: https://github.com/rust-lang/rust/blob/master/tests/ui/hello.rs
-
 ## Output comparison
 
 UI tests store the expected output from the compiler in `.stderr` and `.stdout`

From f84c62112a3f86ac0e0916db07d70b391ce7db30 Mon Sep 17 00:00:00 2001
From: Tshepang Mbambo <hopsi@tuta.io>
Date: Sun, 3 Aug 2025 07:18:26 +0200
Subject: [PATCH 4/5] there is still no official policy

---
 src/doc/rustc-dev-guide/src/crates-io.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/src/crates-io.md b/src/doc/rustc-dev-guide/src/crates-io.md
index 4431585a2f02b..677b1fc03134e 100644
--- a/src/doc/rustc-dev-guide/src/crates-io.md
+++ b/src/doc/rustc-dev-guide/src/crates-io.md
@@ -11,7 +11,7 @@ you should avoid adding dependencies to the compiler for several reasons:
 - The dependency may have transitive dependencies that have one of the above
   problems.
 
-<!-- date-check: Feb 2023 -->
+<!-- date-check: Aug 2025 -->
 Note that there is no official policy for vetting new dependencies to the compiler.
 Decisions are made on a case-by-case basis, during code review.
 

From b8d1af5e5633ff1ac1c9c9a3921af2d8e8620410 Mon Sep 17 00:00:00 2001
From: The rustc-josh-sync Cronjob Bot <github-actions@github.com>
Date: Mon, 4 Aug 2025 04:24:59 +0000
Subject: [PATCH 5/5] Prepare for merging from rust-lang/rust

This updates the rust-version file to 383b9c447b61641e1f1a3850253944a897a60827.
---
 src/doc/rustc-dev-guide/rust-version | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/rustc-dev-guide/rust-version b/src/doc/rustc-dev-guide/rust-version
index 1ced6098acf4b..e9f1626f1fdd4 100644
--- a/src/doc/rustc-dev-guide/rust-version
+++ b/src/doc/rustc-dev-guide/rust-version
@@ -1 +1 @@
-32e7a4b92b109c24e9822c862a7c74436b50e564
+383b9c447b61641e1f1a3850253944a897a60827