[docs] Check link validity in PR

.circleci/config.yml

@@ -181,6 +181,11 @@ jobs:
       - run:
           name: '`yarn l10n` changes committed?'
           command: git diff --exit-code
+      - run:
+          name: '`yarn docs:link-check` changes committed?'
+          command: |
+            yarn docs:link-check
+            git diff --exit-code
   test_browser:
     <<: *defaults
     docker:

babel.config.js

@@ -14,6 +14,7 @@ const defaultAlias = {
   '@mui/x-license-pro': resolveAliasPath('./packages/x-license-pro/src'),
   '@mui/x-date-pickers': resolveAliasPath('./packages/x-date-pickers/src'),
   '@mui/x-date-pickers-pro': resolveAliasPath('./packages/x-date-pickers-pro/src'),
+  '@mui/markdown': '@mui/monorepo/docs/packages/markdown',
   'typescript-to-proptypes': '@mui/monorepo/packages/typescript-to-proptypes/src',
   docs: resolveAliasPath('./node_modules/@mui/monorepo/docs'),
   test: resolveAliasPath('./test'),

docs/.link-check-errors.txt

@@ -0,0 +1,6 @@
+Broken links found by `yarn docs:link-check` that exist:
+
+- https://mui.com/blog/material-ui-v4-is-out/#premium-themes-store-✨
+- https://mui.com/size-snapshot
+- https://mui.com/x/react-data-grid/migration-v4
+- https://mui.com/x/react-date-pickers/migration-lab

docs/data/data-grid/components/components.md

@@ -39,7 +39,7 @@ The grid exposes two hooks to help you to access the grid data while overriding
 
 They can be used as below:
 
-- `useGridApiContext`: returns the `apiRef` object (more details in the [API object page](/x/react-data-grid/api-object/#use-it-inside-the-grid)).
+- `useGridApiContext`: returns the `apiRef` object (more details in the [API object page](/x/react-data-grid/api-object/#inside-the-data-grid)).
 - `useGridSelector`: returns the result of a selector on the current state (more details in the [State page](/x/react-data-grid/state/#access-the-state)).
 
 ```tsx

docs/data/migration/migration-data-grid-v4/migration-data-grid-v4.md

@@ -19,7 +19,7 @@ Most breaking changes are renaming of CSS classes or variables to improve the co
 Using MUI Core v4 with v5 can be achieved with the following steps:
 
 1. First, make sure you have MUI Core v5 installed. If not, install it with these [instructions](/material-ui/getting-started/installation/).
-1. Add a custom [`createGenerateClassName`](/system/styles/api/#heading-creategenerateclassname-options-class-name-generator) to disable the generation of global class names in JSS.
+1. Add a custom [`createGenerateClassName`](/system/styles/api/#creategenerateclassname-options-class-name-generator) to disable the generation of global class names in JSS.
 
 ```jsx
 import { createGenerateClassName } from '@material-ui/core/styles';

docs/scripts/reportBrokenLinks.js

@@ -0,0 +1,68 @@
+/* eslint-disable no-console */
+const path = require('path');
+const fse = require('fs-extra');
+const { parseDocFolder, getAnchor } = require('@mui/monorepo/docs/scripts/reportBrokenLinks');
+
+const docsSpaceRoot = path.join(__dirname, '../');
+
+function save(lines) {
+  const fileContents = [...lines, ''].join('\n');
+  fse.writeFileSync(path.join(docsSpaceRoot, '.link-check-errors.txt'), fileContents);
+}
+
+const UNSUPPORTED_PATHS = ['/api/', '/careers/', '/store/'];
+
+const buffer = [];
+
+function write(text) {
+  buffer.push(text);
+}
+
+// {[url with hash]: true}
+const availableLinksX = {};
+const availableLinksCore = {};
+
+// {[url with hash]: list of files using this link}
+const usedLinksX = {};
+const usedLinksCore = {};
+
+parseDocFolder(path.join(docsSpaceRoot, './pages/'), availableLinksX, usedLinksX, '');
+parseDocFolder(
+  path.resolve(__dirname, '../../node_modules/@mui/monorepo/docs/pages/'),
+  availableLinksCore,
+  usedLinksCore,
+  '',
+);
+
+function getPageUrlFromLink(link) {
+  const [rep] = link.split('/#');
+  return rep;
+}
+
+const usedLinks = { ...usedLinksCore, ...usedLinksX };
+const availableLinks = { ...availableLinksCore, ...availableLinksX };
+
+write('Broken links found by `yarn docs:link-check` that exist:\n');
+Object.keys(usedLinks)
+  .filter((link) => link.startsWith('/'))
+  .filter((link) => !availableLinks[link])
+  // unstyled sections are added by scripts (can not be found in markdown)
+  .filter((link) => !link.includes('#unstyled'))
+  .filter((link) => UNSUPPORTED_PATHS.every((unsupportedPath) => !link.includes(unsupportedPath)))
+  .sort()
+  .forEach((linkKey) => {
+    write(`- https://mui.com${linkKey}`);
+    console.log(`https://mui.com${linkKey}`);
+    console.log(`used in`);
+    usedLinks[linkKey].forEach((f) => console.log(`- ${path.relative(docsSpaceRoot, f)}`));
+    console.log('available anchors on the same page:');
+    console.log(
+      Object.keys(availableLinks)
+        .filter((link) => getPageUrlFromLink(link) === getPageUrlFromLink(linkKey))
+        .sort()
+        .map(getAnchor)
+        .join('\n'),
+    );
+    console.log('\n\n');
+  });
+save(buffer);

package.json

@@ -9,6 +9,7 @@
     "docs:create-playground": "yarn workspace docs create-playground",
     "docs:api": "yarn docs:api:build",
     "docs:api:build": "cross-env BABEL_ENV=development babel-node -i \"/node_modules/(?!@mui)/\" -x .ts,.tsx,.js ./docs/scripts/api/buildApi.ts",
+    "docs:link-check": "cross-env BABEL_ENV=development babel-node -i \"/node_modules/(?!@mui)/\" --extensions \".tsx,.ts,.js\" ./docs/scripts/reportBrokenLinks.js",
     "docs:build": "yarn workspace docs build",
     "docs:export": "yarn workspace docs export",
     "docs:typescript:formatted": "yarn workspace docs typescript:transpile",