[docs] Introduce documentation

.gitignore

@@ -8,6 +8,8 @@
 /.eslintcache
 /.nyc_output
 /coverage
+/docs/.next
+/docs/export
 dist
 node_modules
 __diff_output__

docs/README.md

@@ -0,0 +1,23 @@
+# Material-UI docs
+
+This is the documentation website of Material-UI.
+
+To start the docs site in development mode, from the project root, run:
+
+```sh
+yarn && yarn docs:dev
+```
+
+If you do not have yarn installed, select your OS and follow the instructions on the [Yarn website](https://yarnpkg.com/lang/en/docs/install/#mac-stable).
+
+_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)
+on how to get started contributing to Material-UI.
+
+## How do I help to improve the translations?
+
+Please visit https://translate.material-ui.com/ where you will be able to select a language and edit the translations.
+Please don't submit pull requests directly.

docs/babel.config.js

@@ -0,0 +1,64 @@
+const bpmr = require('babel-plugin-module-resolver');
+const fse = require('fs-extra');
+const path = require('path');
+
+const errorCodesPath = path.resolve(__dirname, './public/static/error-codes.json');
+
+function resolvePath(sourcePath, currentFile, opts) {
+ if (sourcePath === 'markdown') {
+ const base = currentFile.substring(__dirname.length).slice(0, -3);
+ return `${__dirname}/docs/src/${base}/`;
+ }
+
+ return bpmr.resolvePath(sourcePath, currentFile, opts);
+}
+
+const alias = {
+ docs: './',
+ modules: '../node_modules/@material-ui/monorepo/modules',
+ pages: './pages',
+};
+
+const { version: transformRuntimeVersion } = fse.readJSONSync(
+ require.resolve('@babel/runtime-corejs2/package.json'),
+);
+
+module.exports = {
+ presets: [
+ // backport of https://github.com/zeit/next.js/pull/9511
+ ['next/babel', { 'transform-runtime': { corejs: 2, version: transformRuntimeVersion } }],
+ ],
+ plugins: [
+ [
+ 'babel-plugin-macros',
+ {
+ muiError: {
+ errorCodesPath,
+ },
+ },
+ ],
+ 'babel-plugin-optimize-clsx',
+ // for IE 11 support
+ '@babel/plugin-transform-object-assign',
+ 'babel-plugin-preval',
+ [
+ 'babel-plugin-module-resolver',
+ {
+ alias,
+ transformFunctions: ['require', 'require.context'],
+ resolvePath,
+ },
+ ],
+ ],
+ ignore: [/@babel[\\|/]runtime/], // Fix a Windows issue.
+ env: {
+ production: {
+ plugins: [
+ '@babel/plugin-transform-react-constant-elements',
+ 'babel-plugin-transform-dev-warning',
+ ['babel-plugin-react-remove-properties', { properties: ['data-mui-test'] }],
+ ['babel-plugin-transform-react-remove-prop-types', { mode: 'remove' }],
+ ],
+ },
+ },
+};

docs/next-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="next" />
+/// <reference types="next/types/global" />

docs/next.config.js

@@ -0,0 +1,189 @@
+const webpack = require('webpack');
+const path = require('path');
+const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
+const pkg = require('../package.json');
+const { findPages } = require('./src/modules/utils/find');
+const { LANGUAGES, LANGUAGES_SSR } = require('./src/modules/constants');
+
+const workspaceRoot = path.join(__dirname, '../');
+
+/**
+ * https://github.com/zeit/next.js/blob/287961ed9142a53f8e9a23bafb2f31257339ea98/packages/next/next-server/server/config.ts#L10
+ * @typedef {'legacy' | 'blocking' | 'concurrent'} ReactRenderMode
+ * legacy - ReactDOM.render(<App />)
+ * legacy-strict - ReactDOM.render(<React.StrictMode><App /></React.StrictMode>, Element)
+ * blocking - ReactDOM.createSyncRoot(Element).render(<App />)
+ * concurrent - ReactDOM.createRoot(Element).render(<App />)
+ * @type {ReactRenderMode | 'legacy-strict'}
+ */
+const reactMode = 'legacy';
+// eslint-disable-next-line no-console
+console.log(`Using React '${reactMode}' mode.`);
+
+module.exports = {
+ typescript: {
+ // Motivated by https://github.com/zeit/next.js/issues/7687
+ ignoreDevErrors: true,
+ ignoreBuildErrors: true,
+ },
+ webpack: (config, options) => {
+ const plugins = config.plugins.concat([
+ new webpack.DefinePlugin({
+ 'process.env': {
+ ENABLE_AD: JSON.stringify(process.env.ENABLE_AD),
+ GITHUB_AUTH: JSON.stringify(process.env.GITHUB_AUTH),
+ LIB_VERSION: JSON.stringify(pkg.version),
+ REACT_MODE: JSON.stringify(reactMode),
+ },
+ }),
+ ]);
+
+ if (process.env.DOCS_STATS_ENABLED) {
+ plugins.push(
+ // For all options see https://github.com/th0r/webpack-bundle-analyzer#as-plugin
+ new BundleAnalyzerPlugin({
+ analyzerMode: 'server',
+ generateStatsFile: true,
+ // Will be available at `.next/stats.json`
+ statsFilename: 'stats.json',
+ }),
+ );
+ }
+
+ // next includes node_modules in webpack externals. Some of those have dependencies
+ // on the aliases defined above. If a module is an external those aliases won't be used.
+ // We need tell webpack to not consider those packages as externals.
+ if (options.isServer) {
+ const [nextExternals, ...externals] = config.externals;
+
+ if (externals.length > 0) {
+ // currently not the case but other next plugins might introduce additional
+ // rules for externals. We would need to handle those in the callback
+ throw new Error('There are other externals in the webpack config.');
+ }
+
+ config.externals = [
+ (context, request, callback) => {
+ const hasDependencyOnRepoPackages = [
+ 'notistack',
+ 'material-table',
+ '@material-ui/pickers',
+ '@material-ui/monorepo',
+ ].includes(request);
+
+ if (hasDependencyOnRepoPackages) {
+ return callback(null);
+ }
+ return nextExternals(context, request, callback);
+ },
+ ];
+ }
+
+ return {
+ ...config,
+ plugins,
+ node: {
+ fs: 'empty',
+ },
+ module: {
+ ...config.module,
+ rules: config.module.rules.concat([
+ // used in some /getting-started/templates
+ {
+ test: /\.md$/,
+ loader: 'raw-loader',
+ },
+ // transpile 3rd party packages with dependencies in this repository
+ {
+ test: /\.(js|mjs|jsx)$/,
+ include: /node_modules(\/|\\)(material-table|notistack|@material-ui(\/|\\)(pickers|monorepo))/,
+ use: {
+ loader: 'babel-loader',
+ options: {
+ // on the server we use the transpiled commonJS build, on client ES6 modules
+ // babel needs to figure out in what context to parse the file
+ sourceType: 'unambiguous',
+ plugins: [
+ [
+ 'babel-plugin-module-resolver',
+ {
+ alias: {
+ // all packages in this monorepo
+ '@material-ui/core': '../packages/material-ui/src',
+ '@material-ui/docs': '../packages/material-ui-docs/src',
+ '@material-ui/icons': '../packages/material-ui-icons/src',
+ '@material-ui/lab': '../packages/material-ui-lab/src',
+ '@material-ui/styles': '../packages/material-ui-styles/src',
+ '@material-ui/system': '../packages/material-ui-system/src',
+ '@material-ui/utils': '../packages/material-ui-utils/src',
+ },
+ transformFunctions: ['require'],
+ },
+ ],
+ ],
+ },
+ },
+ },
+ // required to transpile ../packages/
+ {
+ test: /\.(js|mjs|jsx|ts)$/,
+ include: [workspaceRoot],
+ exclude: /node_modules/,
+ use: options.defaultLoaders.babel,
+ },
+ ]),
+ },
+ };
+ },
+ exportTrailingSlash: true,
+ trailingSlash: true,
+ // Next.js provides a `defaultPathMap` argument, we could simplify the logic.
+ // However, we don't in order to prevent any regression in the `findPages()` method.
+ exportPathMap: () => {
+ const pages = findPages();
+ const map = {};
+
+ function traverse(pages2, userLanguage) {
+ const prefix = userLanguage === 'en' ? '' : `/${userLanguage}`;
+
+ pages2.forEach((page) => {
+ if (!page.children) {
+ map[`${prefix}${page.pathname.replace(/^\/api-docs\/(.*)/, '/api/$1')}`] = {
+ page: page.pathname,
+ query: {
+ userLanguage,
+ },
+ };
+ return;
+ }
+
+ traverse(page.children, userLanguage);
+ });
+ }
+
+ // We want to speed-up the build of pull requests.
+ if (process.env.PULL_REQUEST === 'true') {
+ // eslint-disable-next-line no-console
+ console.log('Considering only English for SSR');
+ traverse(pages, 'en');
+ } else {
+ // eslint-disable-next-line no-console
+ console.log('Considering various locales for SSR');
+ LANGUAGES_SSR.forEach((userLanguage) => {
+ traverse(pages, userLanguage);
+ });
+ }
+
+ return map;
+ },
+ experimental: {
+ reactMode: reactMode.startsWith('legacy') ? 'legacy' : reactMode,
+ },
+ reactStrictMode: reactMode === 'legacy-strict',
+ async rewrites() {
+ return [
+ { source: `/:lang(${LANGUAGES.join('|')})?/:rest*`, destination: '/:rest*' },
+ { source: '/api/:rest*', destination: '/api-docs/:rest*' },
+ ];
+ },
+};