[core] Move the internal packages from docs/packages

docs/config.js

@@ -0,0 +1,29 @@
+// Valid languages to server-side render in production
+const LANGUAGES = ['en'];
+
+// Server side rendered languages
+const LANGUAGES_SSR = ['en'];
+
+// Work in progress
+const LANGUAGES_IN_PROGRESS = LANGUAGES.slice();
+
+const LANGUAGES_IGNORE_PAGES = (pathname) => {
+  // We don't have the bandwidth like Qt to translate our blog posts
+  // https://www.qt.io/zh-cn/blog
+  if (pathname === '/blog' || pathname.startsWith('/blog/')) {
+    return true;
+  }
+
+  if (pathname === '/size-snapshot/') {
+    return true;
+  }
+
+  return false;
+};
+
+module.exports = {
+  LANGUAGES,
+  LANGUAGES_IN_PROGRESS,
+  LANGUAGES_SSR,
+  LANGUAGES_IGNORE_PAGES,
+};

docs/next.config.js

@@ -3,7 +3,12 @@ const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
 const pkg = require('../package.json');
 const withDocsInfra = require('./nextConfigDocsInfra');
 const { findPages } = require('./src/modules/utils/find');
-const { LANGUAGES, LANGUAGES_SSR, LANGUAGES_IGNORE_PAGES } = require('./src/modules/constants');
+const {
+  LANGUAGES,
+  LANGUAGES_SSR,
+  LANGUAGES_IGNORE_PAGES,
+  LANGUAGES_IN_PROGRESS,
+} = require('./config');
 
 const workspaceRoot = path.join(__dirname, '../');
 
@@ -87,7 +92,16 @@ module.exports = withDocsInfra({
             oneOf: [
               {
                 resourceQuery: /@mui\/markdown/,
-                use: [options.defaultLoaders.babel, require.resolve('@mui/markdown/loader')],
+                use: [
+                  options.defaultLoaders.babel,
+                  {
+                    loader: require.resolve('@mui/markdown/loader'),
+                    options: {
+                      ignoreLanguagePages: LANGUAGES_IGNORE_PAGES,
+                      languagesInProgress: LANGUAGES_IN_PROGRESS,
+                    },
+                  },
+                ],
               },
               {
                 // used in some /getting-started/templates

docs/package.json

@@ -36,6 +36,7 @@
     "@mui/icons-material": "^5.10.16",
     "@mui/joy": "5.0.0-alpha.56",
     "@mui/lab": "5.0.0-alpha.110",
+    "@mui/markdown": "*",
     "@mui/material": "^5.10.16",
     "@mui/material-next": "6.0.0-alpha.64",
     "@mui/styled-engine": "^5.10.16",

docs/scripts/ApiBuilders/ComponentApiBuilder.ts

@@ -12,7 +12,7 @@ import { Link } from 'mdast';
 import { defaultHandlers, parse as docgenParse, ReactDocgenApi } from 'react-docgen';
 import { unstable_generateUtilityClass as generateUtilityClass } from '@mui/utils';
 import muiDefaultPropsHandler from 'docs/src/modules/utils/defaultPropsHandler';
-import { LANGUAGES } from 'docs/src/modules/constants';
+import { LANGUAGES } from 'docs/config';
 import parseTest from 'docs/src/modules/utils/parseTest';
 import generatePropTypeDescription, {
   getChained,

docs/scripts/reportBrokenLinks.js

@@ -3,6 +3,7 @@ const path = require('path');
 const fse = require('fs-extra');
 const { createRender } = require('@mui/markdown');
 const { marked } = require('marked');
+const { LANGUAGES_IGNORE_PAGES } = require('../config');
 
 // Use renderer to extract all links into a markdown document
 const getPageLinks = (markdown) => {
@@ -66,7 +67,12 @@ function getLinksAndAnchors(fileName) {
   const toc = [];
   const headingHashes = {};
   const userLanguage = 'en';
-  const render = createRender({ headingHashes, toc, userLanguage });
+  const render = createRender({
+    headingHashes,
+    toc,
+    userLanguage,
+    ignoreLanguagePages: LANGUAGES_IGNORE_PAGES,
+  });
 
   const data = fse.readFileSync(fileName, { encoding: 'utf8' });
   render(data);

docs/src/modules/components/AppSearch.js

@@ -15,7 +15,7 @@ import KeyboardArrowRightRounded from '@mui/icons-material/KeyboardArrowRightRou
 import SearchIcon from '@mui/icons-material/Search';
 import GlobalStyles from '@mui/material/GlobalStyles';
 import { alpha, styled } from '@mui/material/styles';
-import { LANGUAGES_SSR } from 'docs/src/modules/constants';
+import { LANGUAGES_SSR } from 'docs/config';
 import Link from 'docs/src/modules/components/Link';
 import { useTranslate, useUserLanguage } from 'docs/src/modules/utils/i18n';
 import useLazyCSS from 'docs/src/modules/utils/useLazyCSS';

docs/src/modules/components/Head.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import NextHead from 'next/head';
 import { useRouter } from 'next/router';
-import { LANGUAGES_SSR } from 'docs/src/modules/constants';
+import { LANGUAGES_SSR } from 'docs/config';
 import { useUserLanguage, useTranslate } from 'docs/src/modules/utils/i18n';
 import { pathnameToLanguage } from 'docs/src/modules/utils/helpers';
 

docs/src/modules/components/Link.tsx

@@ -5,7 +5,7 @@ import NextLink, { LinkProps as NextLinkProps } from 'next/link';
 import MuiLink, { LinkProps as MuiLinkProps } from '@mui/material/Link';
 import { styled } from '@mui/material/styles';
 import { useUserLanguage } from 'docs/src/modules/utils/i18n';
-import { LANGUAGES_IGNORE_PAGES } from 'docs/src/modules/constants';
+import { LANGUAGES_IGNORE_PAGES } from 'docs/config';
 
 /**
  * File to keep in sync with:

docs/src/modules/constants.js

@@ -3,15 +3,6 @@ const CODE_VARIANTS = {
   TS: 'TS',
 };
 
-// Valid languages to server-side render in production
-const LANGUAGES = ['en'];
-
-// Server side rendered languages
-const LANGUAGES_SSR = ['en'];
-
-// Work in progress
-const LANGUAGES_IN_PROGRESS = LANGUAGES.slice();
-
 // Valid languages to use in production
 const LANGUAGES_LABEL = [
   {
@@ -20,25 +11,7 @@ const LANGUAGES_LABEL = [
   },
 ];
 
-const LANGUAGES_IGNORE_PAGES = (pathname) => {
-  // We don't have the bandwidth like Qt to translate our blog posts
-  // https://www.qt.io/zh-cn/blog
-  if (pathname === '/blog' || pathname.startsWith('/blog/')) {
-    return true;
-  }
-
-  if (pathname === '/size-snapshot/') {
-    return true;
-  }
-
-  return false;
-};
-
 module.exports = {
   CODE_VARIANTS,
-  LANGUAGES,
-  LANGUAGES_SSR,
   LANGUAGES_LABEL,
-  LANGUAGES_IN_PROGRESS,
-  LANGUAGES_IGNORE_PAGES,
 };

docs/src/modules/utils/helpers.ts

@@ -1,6 +1,6 @@
 import upperFirst from 'lodash/upperFirst';
 import camelCase from 'lodash/camelCase';
-import { LANGUAGES } from '../constants';
+import { LANGUAGES } from 'docs/config';
 
 function pascalCase(str: string) {
   return upperFirst(camelCase(str));

docs/src/modules/utils/mapApiPageTranslations.js

@@ -1,4 +1,5 @@
 import { createRender } from '@mui/markdown';
+import { LANGUAGES_IGNORE_PAGES } from '../../../config';
 
 const notEnglishJsonRegExp = /-([a-z]{2})\.json$/;
 
@@ -29,6 +30,7 @@ export default function mapApiPageTranslations(req) {
         toc: componentDescriptionToc,
         userLanguage,
         location: filenames,
+        ignoreLanguagePages: LANGUAGES_IGNORE_PAGES,
       });
       translation.componentDescription = render(translation.componentDescription);
       translation.componentDescriptionToc = componentDescriptionToc;

package.json

@@ -238,7 +238,6 @@
     "benchmark",
     "packages/*",
     "docs",
-    "docs/packages/*",
     "test"
   ]
 }

packages/markdown/index.d.ts

@@ -0,0 +1,19 @@
+interface TableOfContentsEntry {
+  children: TableOfContentsEntry;
+  hash: string;
+  level: number;
+  text: string;
+}
+
+export function createRender(context: {
+  headingHashes: Record<string, string>;
+  toc: TableOfContentsEntry[];
+  userLanguage: string;
+  ignoreLanguagePages: (path: string) => boolean;
+}): (markdown: string) => string;
+
+export function getHeaders(markdown: string): Record<string, string | string[]>;
+
+export function getTitle(markdown: string): string;
+
+export function renderInline(markdown: string): string;

docs/packages/markdown/loader.js → packages/markdown/loader.js

@@ -4,8 +4,6 @@ const { prepareMarkdown } = require('./parseMarkdown');
 const extractImports = require('./extractImports');
 
 const notEnglishMarkdownRegExp = /-([a-z]{2})\.md$/;
-// TODO: pass as argument
-const LANGUAGES_IN_PROGRESS = ['en', 'zh', 'ru', 'pt', 'es', 'fr', 'de', 'ja'];
 
 /**
  * @param {string} string
@@ -39,14 +37,14 @@ const packages = [
   {
     product: 'material-ui',
     paths: [
-      path.join(__dirname, '../../../packages/mui-lab/src'),
-      path.join(__dirname, '../../../packages/mui-material/src'),
-      path.join(__dirname, '../../../packages/mui-base/src'),
+      path.join(__dirname, '../../packages/mui-lab/src'),
+      path.join(__dirname, '../../packages/mui-material/src'),
+      path.join(__dirname, '../../packages/mui-base/src'),
     ],
   },
   {
     product: 'base',
-    paths: [path.join(__dirname, '../../../packages/mui-base/src')],
+    paths: [path.join(__dirname, '../../packages/mui-base/src')],
   },
 ];
 
@@ -75,6 +73,7 @@ packages.forEach((pkg) => {
  */
 module.exports = async function demoLoader() {
   const englishFilepath = this.resourcePath;
+  const config = this.getOptions();
 
   const englishFilename = path.basename(englishFilepath, '.md');
 
@@ -94,7 +93,7 @@ module.exports = async function demoLoader() {
         if (
           filename.startsWith(englishFilename) &&
           matchNotEnglishMarkdown !== null &&
-          LANGUAGES_IN_PROGRESS.indexOf(matchNotEnglishMarkdown[1]) !== -1
+          config.languagesInProgress.indexOf(matchNotEnglishMarkdown[1]) !== -1
         ) {
           return {
             filename,
@@ -121,7 +120,12 @@ module.exports = async function demoLoader() {
     .replace(this.rootContext, '')
     // win32 to posix
     .replace(/\\/g, '/');
-  const { docs } = prepareMarkdown({ pageFilename, translations, componentPackageMapping });
+  const { docs } = prepareMarkdown({
+    pageFilename,
+    translations,
+    componentPackageMapping,
+    ignoreLanguagePages: config.ignoreLanguagePages,
+  });
 
   const demos = {};
   const importedModuleIDs = new Set();

docs/packages/markdown/parseMarkdown.js → packages/markdown/parseMarkdown.js

@@ -1,7 +1,6 @@
 const { marked } = require('marked');
 const kebabCase = require('lodash/kebabCase');
 const textToHash = require('./textToHash');
-const { LANGUAGES_IGNORE_PAGES } = require('../../src/modules/constants');
 const prism = require('./prism');
 
 const headerRegExp = /---[\r\n]([\s\S]*)[\r\n]---/;
@@ -174,9 +173,10 @@ const noSEOadvantage = [
  * @param {Record<string, string>} context.headingHashes - WILL BE MUTATED
  * @param {TableOfContentsEntry[]} context.toc - WILL BE MUTATED
  * @param {string} context.userLanguage
+ * @param {function(string):boolean} context.ignoreLanguagePages
  */
 function createRender(context) {
-  const { headingHashes, toc, userLanguage } = context;
+  const { headingHashes, toc, userLanguage, ignoreLanguagePages } = context;
   const headingHashesFallbackTranslated = {};
   let headingIndex = -1;
 
@@ -266,7 +266,7 @@ function createRender(context) {
 
       checkUrlHealth(href, linkText, context);
 
-      if (userLanguage !== 'en' && href.indexOf('/') === 0 && !LANGUAGES_IGNORE_PAGES(href)) {
+      if (userLanguage !== 'en' && href.indexOf('/') === 0 && !ignoreLanguagePages(href)) {
         finalHref = `/${userLanguage}${href}`;
       }
 
@@ -371,9 +371,10 @@ function resolveComponentApiUrl(product, componentPkg, component) {
  * @param {object} config
  * @param {Array<{ markdown: string, filename: string, userLanguage: string }>} config.translations - Mapping of locale to its markdown
  * @param {string} config.pageFilename - posix filename relative to nextjs pages directory
+ * @param {function(string):boolean} config.ignoreLanguagePages
  */
 function prepareMarkdown(config) {
-  const { pageFilename, translations, componentPackageMapping = {} } = config;
+  const { pageFilename, translations, componentPackageMapping = {}, ignoreLanguagePages } = config;
 
   const demos = {};
   /**
@@ -444,7 +445,13 @@ ${headers.components
       }
 
       const toc = [];
-      const render = createRender({ headingHashes, toc, userLanguage, location });
+      const render = createRender({
+        headingHashes,
+        toc,
+        userLanguage,
+        location,
+        ignoreLanguagePages,
+      });
 
       const rendered = contents.map((content) => {
         if (/^"(demo|component)": "(.*)"/.test(content)) {

packages/markdown/prism.d.ts

@@ -0,0 +1 @@
+export default function highlight(code: string, language: string): string;

packages/mui-codemod/src/v5.0.0/theme-spacing.test/large-actual.js

@@ -15,7 +15,7 @@ import KeyboardArrowRightRounded from '@mui/icons-material/KeyboardArrowRightRou
 import SearchIcon from '@mui/icons-material/Search';
 import GlobalStyles from '@mui/material/GlobalStyles';
 import { alpha, styled } from '@mui/material/styles';
-import { LANGUAGES_SSR } from 'docs/src/modules/constants';
+import { LANGUAGES_SSR } from 'docs/config';
 import Link from 'docs/src/modules/components/Link';
 import { useTranslate, useUserLanguage } from 'docs/src/modules/utils/i18n';
 import useLazyCSS from 'docs/src/modules/utils/useLazyCSS';

packages/mui-codemod/src/v5.0.0/theme-spacing.test/large-expected.js

@@ -15,7 +15,7 @@ import KeyboardArrowRightRounded from '@mui/icons-material/KeyboardArrowRightRou
 import SearchIcon from '@mui/icons-material/Search';
 import GlobalStyles from '@mui/material/GlobalStyles';
 import { alpha, styled } from '@mui/material/styles';
-import { LANGUAGES_SSR } from 'docs/src/modules/constants';
+import { LANGUAGES_SSR } from 'docs/config';
 import Link from 'docs/src/modules/components/Link';
 import { useTranslate, useUserLanguage } from 'docs/src/modules/utils/i18n';
 import useLazyCSS from 'docs/src/modules/utils/useLazyCSS';

tsconfig.json

@@ -18,7 +18,7 @@
       "@mui/material/*": ["./packages/mui-material/src/*"],
       "@mui/lab": ["./packages/mui-lab/src"],
       "@mui/lab/*": ["./packages/mui-lab/src/*"],
-      "@mui/markdown": ["./docs/packages/markdown"],
+      "@mui/markdown": ["./packages/markdown"],
       "@mui/styled-engine": ["./packages/mui-styled-engine/src"],
       "@mui/styled-engine/*": ["./packages/mui-styled-engine/src/*"],
       "@mui/styled-engine-sc": ["./packages/mui-styled-engine-sc/src"],