mui · Janpot · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -216,11 +216,6 @@ jobs:
           command: |
             pnpm extract-error-codes
             git add -A && git diff --exit-code --staged
-      - run:
-          name: '`pnpm docs:link-check` changes committed?'
-          command: |
-            pnpm docs:link-check
-            git add -A && git diff --exit-code --staged
   test_types:
     <<: *default-job
     resource_class: 'medium+'

diff --git a/docs/.link-check-errors.txt b/docs/.link-check-errors.txt
diff --git a/docs/package.json b/docs/package.json
@@ -3,7 +3,7 @@
   "private": true,
   "license": "MIT",
   "scripts": {
-    "build": "rimraf ./export && cross-env NODE_ENV=production NODE_OPTIONS=--max_old_space_size=8192 next build && pnpm build-sw",
+    "build": "rimraf ./export && cross-env NODE_ENV=production NODE_OPTIONS=--max_old_space_size=8192 next build && pnpm build-sw && pnpm link-check",
     "build:clean": "rimraf .next && pnpm build",
     "build-sw": "node ./scripts/buildServiceWorker.js",
     "dev": "next dev",
@@ -14,7 +14,7 @@
     "typescript": "tsc -p tsconfig.json && tsc -p scripts/tsconfig.json",
     "typescript:transpile": "echo 'Use `pnpm docs:typescript:formatted'` instead && exit 1",
     "typescript:transpile:dev": "echo 'Use `pnpm docs:typescript'` instead && exit 1",
-    "link-check": "tsx ./scripts/reportBrokenLinks.ts"
+    "link-check": "tsx ./scripts/reportBrokenLinks.mts"
   },
   "dependencies": {
     "@babel/core": "^7.28.4",

diff --git a/docs/pages/blog/2020-q3-update.md b/docs/pages/blog/2020-q3-update.md
@@ -92,7 +92,7 @@
 
   <img src="/static/blog/2020-q3-update/react-testing-library.png" alt="" style="width: 640px; margin-bottom: 40px; margin-top: 24px;" />
 
-- 💅 We have completed the first iteration of the unstyled components for v5.<br />You can find a [new version](/material-ui/react-slider/#unstyled) of the slider in the lab without any styles.
+- 💅 We have completed the first iteration of the unstyled components for v5.<br />You can find a [new version](https://v5.mui.com/material-ui/react-slider/#unstyled) of the slider in the lab without any styles.
   The unstyled component weighs in at [5.2 kB gzipped](https://bundlephobia.com/package/@mui/lab@5.0.0-alpha.12), compared with 26 kB for the styled version (when used standalone). The component is best suited for use when you want to fully customize the look, without reimplementing the JavaScript and accessibility logic.<br />
   We're also pushing in this direction to address a concern we hear from large enterprises
   that want to be able to go one layer down in the abstraction, in order to gain more control.
@@ -101,10 +101,10 @@
   import SliderUnstyled from '@mui/lab/SliderUnstyled';
   ```
 
-  Note that we have experimented with headless components (hooks only) in the past. For instance, you can leverage the [useAutocomplete](/material-ui/react-autocomplete/#useautocomplete), and [usePagination](/material-ui/react-pagination/#usepagination) hooks. However, we are pushing with unstyled first as a required step for the next item: ⬇️.
+  Note that we have experimented with headless components (hooks only) in the past. For instance, you can leverage the [useAutocomplete](https://v5.mui.com/material-ui/react-autocomplete/#useautocomplete), and [usePagination](https://v5.mui.com/material-ui/react-pagination/#usepagination) hooks. However, we are pushing with unstyled first as a required step for the next item: ⬇️.
 
 - 👩‍🎨 We have completed the first iteration of the new styling solution of v5.<br />
-  You can find a [new version](/material-ui/react-slider/) of the slider in the lab powered by [Emotion](https://emotion.sh/docs/introduction).<br />
+  You can find a [new version](https://v5.mui.com/material-ui/react-slider/) of the slider in the lab powered by [Emotion](https://emotion.sh/docs/introduction).<br />
   If you are already using styled-components in your application, you can swap Emotion for styled-components 💅. Check this [CodeSandbox](https://codesandbox.io/p/sandbox/sliderstyled-with-styled-components-forked-olc27?file=/package.json) or [CRA](https://github.com/mui/material-ui/tree/HEAD/examples/material-ui-cra-styled-components/) for a demo. It relies on aliases to prevent any bundle size overhead.<br />
   The new styling solution saves 2kB+ gzipped in the bundle compared to JSS, and about 14 kB gzipped if you were already using styled-components or Emotion.<br />
   Last but not least, this change allows us to take advantage of dynamic style props. We will use them for dynamic color props, variant props, and new style props available in the core components.

diff --git a/docs/pages/blog/2021-q3-update.md b/docs/pages/blog/2021-q3-update.md
@@ -44,43 +44,43 @@
 
   <p class="blog-description">After</p>
 
-- [Masonry](/material-ui/react-masonry/). We introduced a new component for use when the `Grid` component leads to wasted space. It's frequently used in dashboards.
+- [Masonry](https://v5.mui.com/material-ui/react-masonry/). We introduced a new component for use when the `Grid` component leads to wasted space. It's frequently used in dashboards.
 
   <a href="/material-ui/react-masonry/"><img loading="lazy" src="/static/blog/2021-q3-update/masonry.png" style="width: 700px;" width="1400" height="906" alt="react-masonry" /></a>
 
 - We introduced a new [package of components without styles](https://www.npmjs.com/package/@mui/base), laying the foundations for supporting multiple design systems with headless components.
   While it was tough to balance the time between working on v5 stable and developing the unstyled components, we still managed to introduce the first few:
-  - [Autocomplete](/material-ui/react-autocomplete/#useautocomplete)
+  - [Autocomplete](https://v5.mui.com/material-ui/react-autocomplete/#useautocomplete)
 
   ```jsx
   import { useAutocomplete } from '@mui/base/AutocompleteUnstyled';
   ```
 
-  - [Button](/material-ui/react-button/#unstyled)
+  - [Button](https://v5.mui.com/material-ui/react-button/#unstyled)
 
   ```jsx
   import { useButton } from '@mui/base/ButtonUnstyled';
   ```
 
-  - [Modal](/material-ui/react-modal/#unstyled)
+  - [Modal](https://v5.mui.com/material-ui/react-modal/#unstyled)
 
   ```jsx
   import { ModalUnstyled } from '@mui/base/ModalUnstyled';
   ```
 
-  - [Slider](/material-ui/react-slider/#unstyled)
+  - [Slider](https://v5.mui.com/material-ui/react-slider/#unstyled)
 
   ```jsx
   import { SliderUnstyled } from '@mui/base/SliderUnstyled';
   ```
 
-  - [Switch](/material-ui/react-switch/#unstyled)
+  - [Switch](https://v5.mui.com/material-ui/react-switch/#unstyled)
 
   ```jsx
   import { useSwitch } from '@mui/base/SwitchUnstyled';
   ```
 
-  - [Portal](/material-ui/react-portal/#unstyled)
+  - [Portal](https://v5.mui.com/material-ui/react-portal/#unstyled)
 
   ```jsx
   import { Portal } from '@mui/base/Portal';

diff --git a/docs/pages/blog/2022-tenerife-retreat.md b/docs/pages/blog/2022-tenerife-retreat.md
@@ -172,7 +172,7 @@
 
 MUI is on track to grow from roughly 20 people to 40 or more by the time we get to our next company retreat in late Q1 2023.
 
-We are constantly interviewing React developers from all around the world, and we are also increasingly looking to hire for non-technical roles such as [People Operations Manager](/careers/people-operations-manager/) in which you could have a huge impact steering the direction of the company's nascent HR department.
+We are constantly interviewing React developers from all around the world, and we are also increasingly looking to hire for non-technical roles such as People Operations Manager in which you could have a huge impact steering the direction of the company's nascent HR department.
 
 Check out [our open roles](/careers/) so you can join us before the next retreat!
 

diff --git a/docs/scripts/reportBrokenLinks.mts b/docs/scripts/reportBrokenLinks.mts
@@ -0,0 +1,41 @@
+import * as path from 'path';
+import { crawl } from '@mui/internal-code-infra/brokenLinksChecker';
+import { globby } from 'globby';
+
+async function main() {
+  // The /blog/ page has pagination that's not persisted in the url.
+  const blogPages = await globby('blog/**/*.js', {
+    cwd: path.resolve(import.meta.dirname, '../pages'),
+  });
+  const blogSeedUrls = blogPages.map((page) => {
+    const pathname = page.replace(/(?:\/index)?\.js$/, '');
+    return `/${pathname}`;
+  });
+
+  const { issues } = await crawl({
+    startCommand: 'pnpm start --no-request-logging -p 3001',
+    host: 'http://localhost:3001/',
+    seedUrls: ['/', ...blogSeedUrls],
+    outPath: path.resolve(import.meta.dirname, '../export/material-ui/link-structure.json'),
+    // Target paths to ignore during link checking
+    ignoredPaths: [
+      // Internal links not on this server
+      // TODO: Seed crawler with stored links from e.g. mui.com/x/link-structure.json
+      /^\/(x|base-ui|joy-ui|store|toolpad)(\/|$)/,
+    ],
+    // CSS selectors for content to ignore during link checking
+    ignoredContent: [
+      // Links used in demos under MemoryRouter
+      // TODO: Create an easier way to identify content under MemoryRouter
+      // (e.g. a class or an option on the demo)
+      '[id^="demo-"] a[href^="/inbox"]',
+      '[id^="demo-"] a[href^="/trash"]',
+      '[id^="demo-"] a[href^="/spam"]',
+      '[id^="demo-"] a[href^="/drafts"]',
+    ],
+  });
+
+  process.exit(issues.length);
+}
+
+main();
diff --git a/docs/scripts/reportBrokenLinks.ts b/docs/scripts/reportBrokenLinks.ts