[docs] Reduce risk of 404 when changing the default branch (#22801)

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,3 @@
 <!-- Thanks so much for your PR, your contribution is appreciated! ❤️ -->
 
-- [ ] I have followed (at least) the [PR section of the contributing guide](https://github.com/mui-org/material-ui/blob/next/CONTRIBUTING.md#sending-a-pull-request).
+- [ ] I have followed (at least) the [PR section of the contributing guide](https://github.com/mui-org/material-ui/blob/HEAD/CONTRIBUTING.md#sending-a-pull-request).

CONTRIBUTING.md

@@ -84,9 +84,9 @@ Make sure the following is true:
 - If a feature is being added:
   - If the result was already achievable with the core library, explain why this feature needs to be added to the core.
   - If this is a common use case, consider adding an example to the documentation.
-- When adding new features or modifying existing, please include tests to confirm the new behavior. You can read more about our test setup in our test [README](https://github.com/mui-org/material-ui/blob/next/test/README.md).
+- When adding new features or modifying existing, please include tests to confirm the new behavior. You can read more about our test setup in our test [README](https://github.com/mui-org/material-ui/blob/HEAD/test/README.md).
 - If props were added or prop types were changed, the TypeScript declarations were updated.
-- When submitting a new component, please add it to the [lab](https://github.com/mui-org/material-ui/tree/next/packages/material-ui-lab).
+- When submitting a new component, please add it to the [lab](https://github.com/mui-org/material-ui/tree/HEAD/packages/material-ui-lab).
 - The branch is not behind its target.
 
 Because we will only merge a Pull Request for which all tests pass. The following items need is true. We will provide assistance if not:

docs/README.md

@@ -14,7 +14,7 @@ _DO NOT USE NPM, use Yarn to install the dependencies._
 
 ## How can I add a new demo to the documentation?
 
-[You can follow this guide](https://github.com/mui-org/material-ui/blob/next/CONTRIBUTING.md)
+[You can follow this guide](https://github.com/mui-org/material-ui/blob/HEAD/CONTRIBUTING.md)
 on how to get started contributing to Material-UI.
 
 ## How do I help to improve the translations?

docs/src/modules/components/AppFooter.js

@@ -165,7 +165,7 @@ function AppFooter(props) {
                 license: (
                   <Link
                     color="inherit"
-                    href="https://github.com/mui-org/material-ui/blob/next/LICENSE"
+                    href={`https://github.com/mui-org/material-ui/blob/v${process.env.LIB_VERSION}/LICENSE`}
                   >
                     {t('license')}
                   </Link>

docs/src/modules/constants.js

@@ -53,6 +53,7 @@ const LANGUAGES_LABEL = [
   },
 ];
 
+// #default-branch-switch
 const SOURCE_CODE_ROOT_URL = 'https://github.com/mui-org/material-ui/blob/next';
 
 module.exports = {

docs/src/pages/customization/default-theme/default-theme.md

@@ -12,5 +12,7 @@ Explore the default theme object:
 > as the `theme` variable is exposed on all the documentation pages.
 > Please note that **the documentation site is using a custom theme**.
 
+<!-- #default-branch-switch -->
+
 If you want to learn more about how the theme is assembled, take a look at [`material-ui/style/createMuiTheme.js`](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/src/styles/createMuiTheme.js),
 and the related imports which `createMuiTheme` uses.

docs/src/pages/customization/globals/globals.md

@@ -31,7 +31,6 @@ const theme = createMuiTheme({
 
 The list of these customization points for each component is documented under the **Component API** section.
 For instance, you can have a look at the [Button](/api/button/#css).
-Alternatively, you can always have a look at the [implementation](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/src/Button/Button.js).
 
 ## Global CSS
 

docs/src/pages/customization/z-index/z-index.md

@@ -5,7 +5,7 @@
 Several Material-UI components utilize `z-index`, employing a default z-index scale in Material-UI
 that has been designed to properly layer drawers, modals, snackbars, tooltips, and more.
 
-[These values](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/src/styles/zIndex.js) start at an arbitrary number, high and specific enough to ideally avoid conflicts.
+The `z-index` values start at an arbitrary number, high and specific enough to ideally avoid conflicts:
 
 - mobile stepper: 1000
 - speed dial: 1050

docs/src/pages/discover-more/changelog/changelog.md

@@ -2,4 +2,4 @@
 
 <p class="description">Material-UI follows Semantic Versioning 2.0.0.</p>
 
-All notable changes are described in the [CHANGELOG.md file](https://github.com/mui-org/material-ui/blob/next/CHANGELOG.md).
+All notable changes are described in the [CHANGELOG.md file](https://github.com/mui-org/material-ui/blob/HEAD/CHANGELOG.md).

docs/src/pages/discover-more/team/team.md

@@ -7,6 +7,6 @@ Material-UI is maintained by a group of invaluable core contributors, with the m
 {{"demo": "pages/discover-more/team/Team.js", "hideToolbar": true, "bg": "inline"}}
 
 Get involved with Material-UI development by [opening an issue](https://github.com/mui-org/material-ui/issues/new) or submitting a pull request.
-Read the [contributing guidelines](https://github.com/mui-org/material-ui/blob/next/CONTRIBUTING.md) for information on how we develop.
+Read the [contributing guidelines](https://github.com/mui-org/material-ui/blob/HEAD/CONTRIBUTING.md) for information on how we develop.
 
 [Join and support the project!](/getting-started/faq/#material-ui-is-awesome-how-can-i-support-the-project)

docs/src/pages/guides/localization/localization.md

@@ -69,6 +69,8 @@ const theme = createMuiTheme(
 | Ukrainian               | uk-UA               | `ukUA`      |
 | Vietnamese              | vi-VN               | `viVN`      |
 
+<!-- #default-branch-switch -->
+
 You can [find the source](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/src/locale/index.ts) in the GitHub repository.
 
 To create your own translation, or to customize the English text, copy this file to your project, make any changes needed and import the locale from there.

docs/src/pages/guides/migration-v4/migration-v4.md

@@ -6,7 +6,7 @@ Looking for the v4 docs? [Find them here](https://material-ui.com/versions/).
 
 > This document is a work in progress.
 > Have you upgraded your site and run into something that's not covered here?
-> [Add your changes on GitHub](https://github.com/mui-org/material-ui/blob/next/docs/src/pages/guides/migration-v4/migration-v4.md).
+> [Add your changes on GitHub](https://github.com/mui-org/material-ui/blob/HEAD/docs/src/pages/guides/migration-v4/migration-v4.md).
 
 ## Introduction
 

docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md

@@ -50,7 +50,7 @@ This is the option we document in all the demos, since it requires no configurat
 It is encouraged for library authors extending the components.
 Head to [Option 2](#option-2) for the approach that yields the best DX and UX.
 
-While importing directly in this manner doesn't use the exports in [`@material-ui/core/index.js`](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/src/index.js), this file can serve as a handy reference as to which modules are public.
+While importing directly in this manner doesn't use the exports in [the main file of `@material-ui/core`](https://unpkg.com/@material-ui/core), this file can serve as a handy reference as to which modules are public.
 
 Be aware that we only support first and second level imports.
 Anything deeper is considered private and can cause issues, such as module duplication in your bundle.
@@ -217,7 +217,7 @@ Enjoy significantly faster start times.
 
 #### 2. Convert all your imports
 
-Finally, you can convert your existing codebase to this option with this [top-level-imports](https://github.com/mui-org/material-ui/blob/next/packages/material-ui-codemod/README.md#top-level-imports) codemod.
+Finally, you can convert your existing codebase to this option with this [top-level-imports codemod](https://www.npmjs.com/package/@material-ui/codemod#top-level-imports).
 It will perform the following diffs:
 
 ```diff

docs/src/pages/guides/testing/testing.md

@@ -18,4 +18,4 @@ We don't recommend snapshot testing though.
 
 Material-UI has **a wide range** of tests so we can
 iterate with confidence on the components, for instance, the visual regression tests provided by [Argos-CI](https://www.argos-ci.com/mui-org/material-ui/builds) have proven to be really helpful.
-To learn more about the internal tests, you can have a look at the [README](https://github.com/mui-org/material-ui/blob/next/test/README.md).
+To learn more about the internal tests, you can have a look at the [README](https://github.com/mui-org/material-ui/blob/HEAD/test/README.md).

docs/src/pages/styles/advanced/advanced.md

@@ -390,11 +390,13 @@ You can [follow the server side guide](/guides/server-rendering/) for a more det
 There is [an official Gatsby plugin](https://github.com/hupe1980/gatsby-plugin-material-ui) that enables server-side rendering for `@material-ui/styles`.
 Refer to the plugin's page for setup and usage instructions.
 
+<!-- #default-branch-switch -->
+
 Refer to [this example Gatsby project](https://github.com/mui-org/material-ui/blob/next/examples/gatsby) for an up-to-date usage example.
 
 ### Next.js
 
-You need to have a custom `pages/_document.js`, then copy [this logic](https://github.com/mui-org/material-ui/blob/next/examples/nextjs/pages/_document.js) to inject the server-side rendered styles into the `<head>` element.
+You need to have a custom `pages/_document.js`, then copy [this logic](https://github.com/mui-org/material-ui/blob/814fb60bbd8e500517b2307b6a297a638838ca89/examples/nextjs/pages/_document.js#L52-L59) to inject the server-side rendered styles into the `<head>` element.
 
 Refer to [this example project](https://github.com/mui-org/material-ui/blob/next/examples/nextjs) for an up-to-date usage example.
 

docs/src/pages/styles/basics/basics.md

@@ -15,6 +15,9 @@ and **unlocks many great features** (theme nesting, dynamic styles, self-support
 Material-UI's styling solution is inspired by many other styling libraries such as [styled-components](https://www.styled-components.com/) and [emotion](https://emotion.sh/).
 
 - 💅 You can expect [the same advantages](https://www.styled-components.com/docs/basics#motivation) as styled-components.
+
+<!-- #default-branch-switch -->
+
 - 🚀 It's [blazing fast](https://github.com/mui-org/material-ui/blob/next/packages/material-ui-benchmark/README.md#material-uistyles).
 - 🧩 It's extensible via a [plugin](https://github.com/cssinjs/jss/blob/master/docs/plugins.md) API.
 - ⚡️ It uses [JSS](https://github.com/cssinjs/jss) at its core – a [high performance](https://github.com/cssinjs/jss/blob/master/docs/performance.md) JavaScript to CSS compiler which works at runtime and server-side.

packages/material-ui/src/CssBaseline/CssBaseline.spec.tsx

@@ -3,7 +3,7 @@ import { createMuiTheme } from '@material-ui/core';
 // overrides story
 {
   // reduced example from
-  // https://github.com/mui-org/material-ui/blob/next/docs/src/pages/customization/typography/typography.md
+  // https://github.com/mui-org/material-ui/blob/HEAD/docs/src/pages/customization/typography/typography.md
   createMuiTheme({
     components: {
       MuiCssBaseline: {

test/README.md

@@ -127,11 +127,11 @@ If you want to `grep` for certain tests add `-g STRING_TO_GREP`.
 
 First, we have the **unit test** suite.
 It uses [mocha](https://mochajs.org) and a thin wrapper around `@testing-library/react`.
-Here is an [example](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/src/Dialog/Dialog.test.js#L87) with the `Dialog` component.
+Here is an [example](https://github.com/mui-org/material-ui/blob/814fb60bbd8e500517b2307b6a297a638838ca89/packages/material-ui/src/Dialog/Dialog.test.js#L71-L80) with the `Dialog` component.
 
 Next, we have the **integration** tests. They are mostly used for components that
 act as composite widgets like `Select` or `Menu`.
-Here is an [example](https://github.com/mui-org/material-ui/blob/next/packages/material-ui/test/integration/Menu.test.js#L28) with the `Menu` component.
+Here is an [example](https://github.com/mui-org/material-ui/blob/814fb60bbd8e500517b2307b6a297a638838ca89/packages/material-ui/test/integration/Menu.test.js#L98-L108) with the `Menu` component.
 
 #### Create HTML coverage reports
 
@@ -169,7 +169,7 @@ Next, we are using [docker](https://github.com/docker/docker) to take screenshot
 ![before](/test/docs-regressions-before.png)
 ![diff](/test/docs-regressions-diff.png)
 
-Here is an [example](https://github.com/mui-org/material-ui/blob/next/test/regressions/tests/Menu/SimpleMenuList.js#L6) with the `Menu` component.
+Here is an [example](https://github.com/mui-org/material-ui/blob/814fb60bbd8e500517b2307b6a297a638838ca89/test/regressions/tests/Menu/SimpleMenuList.js#L6-L16) with the `Menu` component.
 
 #### Installation