chore(website): upgrade to DocSearch 4.4.0 + fix little website theming issues (#11626)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
Co-authored-by: sebastien <lorber.sebastien@gmail.com>

.cspell.json

@@ -0,0 +1,48 @@
+{
+  "version": "0.2",
+  "gitignoreRoot": ".",
+  "useGitignore": true,
+  "dictionaries": [
+    "css",
+    "html",
+    "fonts",
+    "typescript",
+    "softwareTerms",
+    "companies",
+    "lorem-ipsum",
+    "project-words"
+  ],
+  "dictionaryDefinitions": [
+    {
+      "name": "project-words",
+      "path": "./project-words.txt",
+      "noSuggest": true
+    }
+  ],
+  "ignorePaths": [
+    "CHANGELOG.md",
+    "CHANGELOG-v*.md",
+    "patches",
+    "packages/docusaurus-theme-translations/locales",
+    "packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy",
+    "package.json",
+    "yarn.lock",
+    "project-words.txt",
+    "__snapshots__",
+    "admin/scripts",
+    "website/src/data/users.tsx",
+    "website/src/data/tweets.tsx",
+    "website/docusaurus.config.localized.json",
+    "website/_dogfooding/_pages tests/diagrams.mdx",
+    "*.xyz",
+    "*.docx",
+    "*.xsl",
+    "*.xslt",
+    "*.gitignore",
+    "versioned_docs",
+    "*.min.*",
+    "jest/vendor"
+  ],
+  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"],
+  "enableFiletypes": ["mdx"]
+}

.devcontainer/devcontainer.json

@@ -1,10 +1,37 @@
 {
-  "name": "Docusaurus Dev Container",
-  "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:14-buster",
-  "settings": {
-    "terminal.integrated.shell.linux": "/bin/bash"
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "[typescript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        },
+        "[json]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        },
+        "[jsonc]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        }
+      },
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "orta.vscode-jest",
+        "esbenp.prettier-vscode",
+        "streetsidesoftware.code-spell-checker"
+      ]
+    }
   },
-  "extensions": ["dbaeumer.vscode-eslint", "orta.vscode-jest"],
   "forwardPorts": [3000],
-  "postCreateCommand": "yarn install"
+  "containerUser": "vscode",
+  "postCreateCommand": "yarn install",
+  "waitFor": "postCreateCommand", // otherwise automated jest tests fail
+  "features": {
+    "node": {
+      "version": "22"
+    },
+    "github-cli": "latest"
+  }
 }

.eslintignore

@@ -1,21 +1,27 @@
 __fixtures__
+__mocks__
 dist
 node_modules
 .yarn
+.history
 build
 coverage
 jest.config.js
 jest.transform.js
-scripts
+jest/vendor
 examples/
 
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*
-packages/docusaurus-*/lib-next/
-packages/docusaurus-plugin-pwa/copyUntypedFiles.js
-packages/docusaurus-plugin-ideal-image/copyUntypedFiles.js
-packages/docusaurus-theme-search-algolia/copyUntypedFiles.js
+packages/eslint-plugin/lib/
+packages/stylelint-copyright/lib/
 
 packages/create-docusaurus/lib/*
-packages/create-docusaurus/templates/facebook/.eslintrc.js
+packages/create-docusaurus/templates/facebook
+
+website/_dogfooding/_swizzle_theme_tests
+website/_dogfooding/_asset-tests/badSyntax.js
+
+
+packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy

.eslintrc.js

@@ -9,6 +9,20 @@ const OFF = 0;
 const WARNING = 1;
 const ERROR = 2;
 
+// Prevent importing lodash, usually for browser bundle size reasons
+const LodashImportPatterns = ['lodash', 'lodash.**', 'lodash/**'];
+
+// Prevent importing content plugins, usually for coupling reasons
+const ContentPluginsImportPatterns = [
+  '@docusaurus/plugin-content-blog',
+  '@docusaurus/plugin-content-blog/**',
+  // TODO fix theme-common => docs dependency issue
+  // '@docusaurus/plugin-content-docs',
+  // '@docusaurus/plugin-content-docs/**',
+  '@docusaurus/plugin-content-pages',
+  '@docusaurus/plugin-content-pages/**',
+];
+
 module.exports = {
   root: true,
   env: {
@@ -19,18 +33,23 @@ module.exports = {
   },
   parser: '@typescript-eslint/parser',
   parserOptions: {
-    allowImportExportEverywhere: true,
+    // tsconfigRootDir: __dirname,
+    // project: ['./tsconfig.base.json', './website/tsconfig.base.json'],
   },
   globals: {
-    testStylelintRule: true,
+    JSX: true,
   },
   extends: [
     'eslint:recommended',
-    'plugin:@typescript-eslint/eslint-recommended',
-    'plugin:@typescript-eslint/recommended',
     'plugin:react-hooks/recommended',
+    'plugin:jest/recommended',
     'airbnb',
+    'plugin:@typescript-eslint/recommended',
+    // 'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    // 'plugin:@typescript-eslint/strict',
+    'plugin:regexp/recommended',
     'prettier',
+    'plugin:@docusaurus/all',
   ],
   settings: {
     'import/resolver': {
@@ -39,21 +58,167 @@ module.exports = {
       },
     },
   },
-  plugins: ['react-hooks', 'header'],
+  reportUnusedDisableDirectives: true,
+  plugins: [
+    'react-compiler',
+    'react-hooks',
+    'header',
+    'jest',
+    '@typescript-eslint',
+    'regexp',
+    '@docusaurus',
+  ],
   rules: {
-    'react-hooks/rules-of-hooks': ERROR,
-    'react-hooks/exhaustive-deps': ERROR,
+    'react-compiler/react-compiler': ERROR,
+    'react/jsx-uses-react': OFF, // JSX runtime: automatic
+    'react/react-in-jsx-scope': OFF, // JSX runtime: automatic
+    'array-callback-return': WARNING,
+    camelcase: WARNING,
     'class-methods-use-this': OFF, // It's a way of allowing private variables.
-    'func-names': OFF,
-    // Ignore certain webpack alias because it can't be resolved
-    'import/no-unresolved': [
-      ERROR,
+    curly: [WARNING, 'all'],
+    'global-require': WARNING,
+    'lines-between-class-members': OFF,
+    'max-classes-per-file': OFF,
+    'max-len': [
+      WARNING,
       {
-        ignore: ['^@theme', '^@docusaurus', '^@generated', '^@site'],
+        code: Infinity, // Code width is already enforced by Prettier
+        tabWidth: 2,
+        comments: 80,
+        ignoreUrls: true,
+        ignorePattern: '(eslint-disable|@)',
       },
     ],
-    'import/extensions': OFF,
+    'arrow-body-style': OFF,
+    'no-await-in-loop': OFF,
+    'no-case-declarations': WARNING,
+    'no-console': OFF,
+    'no-constant-binary-expression': ERROR,
+    'no-continue': OFF,
+    'no-control-regex': WARNING,
+    'no-else-return': OFF,
+    'no-empty': [WARNING, {allowEmptyCatch: true}],
+    'no-lonely-if': WARNING,
+    'no-nested-ternary': WARNING,
+    'no-param-reassign': [WARNING, {props: false}],
+    'no-prototype-builtins': WARNING,
     'no-restricted-exports': OFF,
+    'no-restricted-properties': [
+      ERROR,
+      .../** @type {[string, string][]} */ ([
+        // TODO: TS doesn't make Boolean a narrowing function yet,
+        // so filter(Boolean) is problematic type-wise
+        // ['compact', 'Array#filter(Boolean)'],
+        ['concat', 'Array#concat'],
+        ['drop', 'Array#slice(n)'],
+        ['dropRight', 'Array#slice(0, -n)'],
+        ['fill', 'Array#fill'],
+        ['filter', 'Array#filter'],
+        ['find', 'Array#find'],
+        ['findIndex', 'Array#findIndex'],
+        ['first', 'foo[0]'],
+        ['flatten', 'Array#flat'],
+        ['flattenDeep', 'Array#flat(Infinity)'],
+        ['flatMap', 'Array#flatMap'],
+        ['fromPairs', 'Object.fromEntries'],
+        ['head', 'foo[0]'],
+        ['indexOf', 'Array#indexOf'],
+        ['initial', 'Array#slice(0, -1)'],
+        ['join', 'Array#join'],
+        // Unfortunately there's no great alternative to _.last yet
+        // Candidates: foo.slice(-1)[0]; foo[foo.length - 1]
+        // Array#at is ES2022; could replace _.nth as well
+        // ['last'],
+        ['map', 'Array#map'],
+        ['reduce', 'Array#reduce'],
+        ['reverse', 'Array#reverse'],
+        ['slice', 'Array#slice'],
+        ['take', 'Array#slice(0, n)'],
+        ['takeRight', 'Array#slice(-n)'],
+        ['tail', 'Array#slice(1)'],
+      ]).map(([property, alternative]) => ({
+        object: '_',
+        property,
+        message: `Use ${alternative} instead.`,
+      })),
+      ...[
+        'readdirSync',
+        'readFileSync',
+        'statSync',
+        'lstatSync',
+        'existsSync',
+        'pathExistsSync',
+        'realpathSync',
+        'mkdirSync',
+        'mkdirpSync',
+        'mkdirsSync',
+        'writeFileSync',
+        'writeJsonSync',
+        'outputFileSync',
+        'outputJsonSync',
+        'moveSync',
+        'copySync',
+        'copyFileSync',
+        'ensureFileSync',
+        'ensureDirSync',
+        'ensureLinkSync',
+        'ensureSymlinkSync',
+        'unlinkSync',
+        'removeSync',
+        'emptyDirSync',
+      ].map((property) => ({
+        object: 'fs',
+        property,
+        message: 'Do not use sync fs methods.',
+      })),
+    ],
+    'no-restricted-syntax': [
+      WARNING,
+      // Copied from airbnb, removed for...of statement, added export all
+      {
+        selector: 'ForInStatement',
+        message:
+          'for..in loops iterate over the entire prototype chain, which is virtually never what you want. Use Object.{keys,values,entries}, and iterate over the resulting array.',
+      },
+      {
+        selector: 'LabeledStatement',
+        message:
+          'Labels are a form of GOTO; using them makes code confusing and hard to maintain and understand.',
+      },
+      {
+        selector: 'WithStatement',
+        message:
+          '`with` is disallowed in strict mode because it makes code impossible to predict and optimize.',
+      },
+      {
+        selector: 'ExportAllDeclaration',
+        message:
+          "Export all does't work well if imported in ESM due to how they are transpiled, and they can also lead to unexpected exposure of internal methods.",
+      },
+      // TODO make an internal plugin to ensure this
+      // {
+      //   selector:
+      // @   'ExportDefaultDeclaration > Identifier, ExportNamedDeclaration[source=null] > ExportSpecifier',
+      //   message: 'Export in one statement'
+      // },
+      ...['path', 'fs-extra', 'webpack', 'lodash'].map((m) => ({
+        selector: `ImportDeclaration[importKind=value]:has(Literal[value=${m}]) > ImportSpecifier[importKind=value]`,
+        message:
+          'Default-import this, both for readability and interoperability with ESM',
+      })),
+    ],
+    'no-template-curly-in-string': WARNING,
+    'no-unused-expressions': [
+      WARNING,
+      {allowTaggedTemplates: true, allowShortCircuit: true},
+    ],
+    'no-useless-escape': WARNING,
+    'no-void': [ERROR, {allowAsStatement: true}],
+    'prefer-destructuring': OFF,
+    'prefer-named-capture-group': WARNING,
+    'prefer-template': WARNING,
+    yoda: WARNING,
+
     'header/header': [
       ERROR,
       'block',
@@ -66,23 +231,103 @@ module.exports = {
         ' ',
       ],
     ],
+
+    'import/extensions': OFF,
+    // This rule doesn't yet support resolving .js imports when the actual file
+    // is .ts. Plus it's not all that useful when our code is fully TS-covered.
+    'import/no-unresolved': [
+      OFF,
+      {
+        // Ignore certain webpack aliases because they can't be resolved
+        ignore: [
+          '^@theme',
+          '^@docusaurus',
+          '^@generated',
+          '^@site',
+          '^@testing-utils',
+        ],
+      },
+    ],
+    'import/order': [
+      WARNING,
+      {
+        groups: [
+          'builtin',
+          'external',
+          'internal',
+          ['parent', 'sibling', 'index'],
+          'type',
+        ],
+        pathGroups: [
+          // always put css import to the last, ref:
+          // https://github.com/import-js/eslint-plugin-import/issues/1239
+          {
+            pattern: '*.+(css|sass|less|scss|pcss|styl)',
+            group: 'unknown',
+            patternOptions: {matchBase: true},
+            position: 'after',
+          },
+          {pattern: '@jest/globals', group: 'builtin', position: 'before'},
+          {pattern: 'react', group: 'builtin', position: 'before'},
+          {pattern: 'react-dom', group: 'builtin', position: 'before'},
+          {pattern: 'react-dom/**', group: 'builtin', position: 'before'},
+          {pattern: 'stream', group: 'builtin', position: 'before'},
+          {pattern: 'fs-extra', group: 'builtin'},
+          {pattern: 'lodash', group: 'external', position: 'before'},
+          {pattern: 'clsx', group: 'external', position: 'before'},
+          // 'Bit weird to not use the `import/internal-regex` option, but this
+          // way, we can make `import type { Props } from "@theme/*"` appear
+          // before `import styles from "styles.module.css"`, which is what we
+          // always did. This should be removable once we stop using ambient
+          // module declarations for theme aliases.
+          {pattern: '@theme/**', group: 'internal'},
+          {pattern: '@site/**', group: 'internal'},
+          {pattern: '@theme-init/**', group: 'internal'},
+          {pattern: '@theme-original/**', group: 'internal'},
+        ],
+        pathGroupsExcludedImportTypes: [],
+        // example: let `import './nprogress.css';` after importing others
+        // in `packages/docusaurus-theme-classic/src/nprogress.ts`
+        // see more: https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/order.md#warnonunassignedimports-truefalse
+        warnOnUnassignedImports: true,
+      },
+    ],
+    'import/prefer-default-export': OFF,
+
+    'jest/consistent-test-it': WARNING,
+    'jest/expect-expect': OFF,
+    'jest/no-large-snapshots': [
+      WARNING,
+      {maxSize: Infinity, inlineMaxSize: 50},
+    ],
+    'jest/no-test-return-statement': ERROR,
+    'jest/prefer-expect-resolves': WARNING,
+    'jest/prefer-lowercase-title': [WARNING, {ignore: ['describe']}],
+    'jest/prefer-spy-on': WARNING,
+    'jest/prefer-to-be': OFF,
+    'jest/prefer-to-have-length': WARNING,
+    'jest/require-top-level-describe': ERROR,
+    'jest/valid-title': [
+      ERROR,
+      {
+        mustNotMatch: {
+          it: [
+            '^should|\\.$',
+            'Titles should not begin with "should" or end with a full-stop',
+          ],
+        },
+      },
+    ],
+
     'jsx-a11y/click-events-have-key-events': WARNING,
     'jsx-a11y/no-noninteractive-element-interactions': WARNING,
     'jsx-a11y/html-has-lang': OFF,
-    'no-console': OFF,
-    'no-else-return': OFF,
-    'no-param-reassign': [WARNING, {props: false}],
-    'no-underscore-dangle': OFF,
-    curly: [WARNING, 'all'],
-    'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.
-    'react/jsx-filename-extension': OFF,
-    'react/jsx-one-expression-per-line': OFF,
-    'react/no-array-index-key': OFF, // Sometimes its ok, e.g. non-changing data.
-    'react/prop-types': OFF,
-    'react/destructuring-assignment': OFF, // Too many lines.
-    'react/prefer-stateless-function': WARNING,
-    'react/jsx-props-no-spreading': OFF,
-    'react/require-default-props': [ERROR, {ignoreFunctionalComponents: true}],
+
+    'react-hooks/rules-of-hooks': ERROR,
+    'react-hooks/exhaustive-deps': ERROR,
+
+    // Sometimes we do need the props as a whole, e.g. when spreading
+    'react/destructuring-assignment': OFF,
     'react/function-component-definition': [
       WARNING,
       {
@@ -90,95 +335,158 @@ module.exports = {
         unnamedComponents: 'arrow-function',
       },
     ],
+    'react/jsx-filename-extension': OFF,
+    'react/jsx-key': [ERROR, {checkFragmentShorthand: true}],
+    'react/jsx-no-useless-fragment': [ERROR, {allowExpressions: true}],
+    'react/jsx-props-no-spreading': OFF,
+    'react/no-array-index-key': OFF, // We build a static site, and nearly all components don't change.
     'react/no-unstable-nested-components': [WARNING, {allowAsProps: true}],
-    '@typescript-eslint/no-inferrable-types': OFF,
-    'import/first': OFF,
-    'import/order': OFF,
-    'import/prefer-default-export': OFF,
-    'lines-between-class-members': OFF,
-    'no-lonely-if': WARNING,
-    'no-use-before-define': OFF,
-    '@typescript-eslint/no-use-before-define': [
-      ERROR,
-      {functions: false, classes: false, variables: true},
-    ],
-    'no-unused-vars': OFF,
-    'no-nested-ternary': WARNING,
-    '@typescript-eslint/no-empty-function': OFF,
-    '@typescript-eslint/no-non-null-assertion': OFF,
-    '@typescript-eslint/no-unused-vars': [
-      ERROR,
-      {argsIgnorePattern: '^_', ignoreRestSiblings: true},
-    ],
-    '@typescript-eslint/explicit-module-boundary-types': WARNING,
+    'react/prefer-stateless-function': WARNING,
+    'react/prop-types': OFF,
+    'react/require-default-props': [ERROR, {ignoreFunctionalComponents: true}],
+
+    '@typescript-eslint/consistent-type-definitions': OFF,
+    '@typescript-eslint/require-await': OFF,
+
     '@typescript-eslint/ban-ts-comment': [
       ERROR,
       {'ts-expect-error': 'allow-with-description'},
     ],
-    'import/no-extraneous-dependencies': ERROR,
-    'no-useless-escape': WARNING,
-    'prefer-template': WARNING,
-    'no-template-curly-in-string': WARNING,
-    'array-callback-return': WARNING,
-    camelcase: WARNING,
-    'no-restricted-syntax': WARNING,
-    'no-unused-expressions': WARNING,
-    'global-require': WARNING,
-    'prefer-destructuring': WARNING,
-    yoda: WARNING,
-    'no-await-in-loop': OFF,
-    'no-control-regex': WARNING,
-    'no-empty': [WARNING, {allowEmptyCatch: true}],
-    'no-prototype-builtins': WARNING,
-    'no-case-declarations': WARNING,
-    'no-undef': OFF,
-    'no-shadow': OFF,
-    '@typescript-eslint/no-shadow': ERROR,
-    'no-redeclare': OFF,
-    '@typescript-eslint/no-redeclare': ERROR,
+    '@typescript-eslint/consistent-indexed-object-style': OFF,
+    '@typescript-eslint/consistent-type-imports': [
+      WARNING,
+      {disallowTypeAnnotations: false},
+    ],
+    '@typescript-eslint/explicit-module-boundary-types': WARNING,
+    '@typescript-eslint/method-signature-style': ERROR,
+    '@typescript-eslint/no-empty-function': OFF,
     '@typescript-eslint/no-empty-interface': [
       ERROR,
       {
         allowSingleExtends: true,
       },
     ],
-    '@typescript-eslint/method-signature-style': ERROR,
-    'no-restricted-imports': [
+    '@typescript-eslint/no-inferrable-types': OFF,
+    '@typescript-eslint/no-namespace': [WARNING, {allowDeclarations: true}],
+    'no-use-before-define': OFF,
+    '@typescript-eslint/no-use-before-define': [
+      ERROR,
+      {functions: false, classes: false, variables: true},
+    ],
+    '@typescript-eslint/no-non-null-assertion': OFF,
+    'no-redeclare': OFF,
+    '@typescript-eslint/no-redeclare': ERROR,
+    'no-shadow': OFF,
+    '@typescript-eslint/no-shadow': ERROR,
+    'no-unused-vars': OFF,
+    // We don't provide any escape hatches for this rule. Rest siblings and
+    // function placeholder params are always ignored, and any other unused
+    // locals must be justified with a disable comment.
+    '@typescript-eslint/no-unused-vars': [
       ERROR,
       {
-        paths: [
-          {
-            name: 'lodash',
-            importNames: [
-              // 'compact', // TODO: TS doesn't make Boolean a narrowing function yet, so filter(Boolean) is problematic type-wise
-              'filter',
-              'flatten',
-              'flatMap',
-              'map',
-              'reduce',
-              'take',
-              'takeRight',
-              'head',
-              'tail',
-              'initial',
-            ],
-            message: 'These APIs have their ES counterparts.',
-          },
+        ignoreRestSiblings: true,
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
+    '@typescript-eslint/prefer-optional-chain': ERROR,
+    '@docusaurus/no-html-links': ERROR,
+    '@docusaurus/prefer-docusaurus-heading': ERROR,
+    '@docusaurus/no-untranslated-text': [
+      WARNING,
+      {
+        ignoredStrings: [
+          '·',
+          '-',
+          '—',
+          '×',
+          '​', // zwj: ​
+          '@',
+          'WebContainers',
+          'Twitter',
+          'X',
+          'GitHub',
+          'Dev.to',
+          '1.x',
         ],
       },
     ],
   },
   overrides: [
+    {
+      files: ['packages/docusaurus/src/client/**/*.{js,ts,tsx}'],
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: [
+              ...LodashImportPatterns,
+              ...ContentPluginsImportPatterns,
+              // Prevent importing server code in client bundle
+              '**/../babel/**',
+              '**/../server/**',
+              '**/../commands/**',
+              '**/../webpack/**',
+            ],
+          },
+        ],
+      },
+    },
     {
       files: [
-        'packages/create-docusaurus/templates/**/*.js',
-        'packages/create-docusaurus/templates/**/*.ts',
-        'packages/create-docusaurus/templates/**/*.tsx',
+        'packages/docusaurus-theme-common/src/**/*.{js,ts,tsx}',
+        'packages/docusaurus-utils-common/src/**/*.{js,ts,tsx}',
       ],
+      excludedFiles: '*.test.{js,ts,tsx}',
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: [
+              ...LodashImportPatterns,
+              ...ContentPluginsImportPatterns,
+            ],
+          },
+        ],
+      },
+    },
+    {
+      files: ['packages/docusaurus-*/src/theme/**/*.{js,ts,tsx}'],
+      excludedFiles: '*.test.{js,ts,tsx}',
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: LodashImportPatterns.concat(
+              // Prevents relative imports between React theme components
+              [
+                '../**',
+                './**',
+                // Allows relative styles module import with consistent filename
+                '!./styles.module.css',
+              ],
+            ),
+          },
+        ],
+      },
+    },
+    {
+      files: [
+        'packages/docusaurus-*/src/theme/**/*.{js,ts,tsx}',
+        'packages/docusaurus/src/client/theme-fallback/**/*.{js,ts,tsx}',
+      ],
+      rules: {
+        'import/no-named-export': ERROR,
+      },
+    },
+    {
+      files: ['packages/create-docusaurus/templates/**/*.{js,ts,tsx}'],
       rules: {
         'header/header': OFF,
         'global-require': OFF,
         '@typescript-eslint/no-var-requires': OFF,
+        '@docusaurus/no-untranslated-text': OFF,
       },
     },
     {
@@ -188,18 +496,58 @@ module.exports = {
       },
     },
     {
-      files: ['*.ts', '*.tsx'],
+      files: ['*.{ts,tsx}'],
       rules: {
+        'no-undef': OFF,
         'import/no-import-module-exports': OFF,
       },
     },
     {
-      files: ['*.js'],
+      files: ['*.{js,mjs,cjs}'],
       rules: {
         // Make JS code directly runnable in Node.
         '@typescript-eslint/no-var-requires': OFF,
         '@typescript-eslint/explicit-module-boundary-types': OFF,
       },
     },
+    {
+      files: [
+        '**/__tests__/**',
+        'packages/docusaurus-plugin-debug/**',
+        'website/_dogfooding/**',
+      ],
+      rules: {
+        '@docusaurus/no-untranslated-text': OFF,
+      },
+    },
+    {
+      // Internal files where extraneous deps don't matter much at long as
+      // they run
+      files: [
+        '*.test.{js,ts,tsx}',
+        'admin/**',
+        'jest/**',
+        'website/**',
+        'packages/docusaurus-theme-common/removeThemeInternalReexport.mjs',
+        'packages/docusaurus-theme-translations/update.mjs',
+        'packages/docusaurus-theme-translations/src/utils.ts',
+      ],
+      rules: {
+        'import/no-extraneous-dependencies': OFF,
+      },
+    },
+    {
+      files: ['packages/eslint-plugin/**/*.{js,ts}'],
+      extends: ['plugin:eslint-plugin/recommended'],
+    },
+    {
+      files: [
+        'packages/docusaurus-plugin-debug/**',
+        'packages/docusaurus/src/**',
+      ],
+      rules: {
+        '@docusaurus/prefer-docusaurus-heading': OFF,
+      },
+    },
   ],
 };

.gitattributes

@@ -27,3 +27,18 @@
 *.bz2 binary
 *.swp binary
 *.webp binary
+
+# Make GitHub not index certain files in the languages overview
+# See https://github.com/github/linguist/blob/master/docs/overrides.md
+# generated files' diff will be minimized
+**/__fixtures__/**                        linguist-generated
+**/__mocks__/**                           linguist-generated
+examples/**                               linguist-generated
+.husky/**                                 linguist-vendored
+jest/**                                   linguist-vendored
+admin/**                                  linguist-documentation
+website/**                                linguist-documentation
+packages/create-docusaurus/templates/**   linguist-vendored
+.eslintrc.*                               linguist-vendored
+jest.config.*                             linguist-vendored
+.stylelintrc.*                            linguist-vendored

.github/ISSUE_TEMPLATE.md

@@ -1,3 +0,0 @@
-## 👉 [Please follow one of these issue templates](https://github.com/facebook/docusaurus/issues/new/choose) 👈
-
-Note: to keep the backlog clean and actionable, issues may be immediately closed if they do not follow one of the above issue templates.

.github/ISSUE_TEMPLATE/bug.yml

@@ -7,7 +7,14 @@ body:
       value: |
         ## Please help us help you!
 
-        Make it obvious to understand and reproduce this bug. Ideally, we should be able to understand it without running any code.
+        Before filing your issue, ask yourself:
+        - Is this clearly a Docusaurus defect?
+        - Do I have basic ideas about where it goes wrong? (For example, if there are stack traces, are they pointing to one file?)
+        - Could it be because of my own mistakes?
+
+        **The GitHub issue tracker is not a support forum**. If you are not sure whether it could be your mistakes, ask in the [Discord server](https://discord.gg/docusaurus) or [GitHub discussions](https://github.com/facebook/docusaurus/discussions) first. The quickest way to verify whether it's a Docusaurus defect is through a **reproduction**, starting with a fresh installation and making changes until the bug is reproduced.
+
+        Make the bug obvious. Ideally, we should be able to understand it without running any code.
 
         Bugs are fixed faster if you include:
         - A repro repository to inspect the code
@@ -19,7 +26,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: checkboxes
@@ -41,13 +48,27 @@ body:
     validations:
       required: true
 
+  - type: input
+    attributes:
+      label: Reproducible demo
+      description: |
+        Paste the link to an example repo, including a `docusaurus.config.js`, and exact instructions to reproduce the issue. It can either be a playground link created from https://new.docusaurus.io, or a git repository.
+
+        > **What happens if you skip this step?** Someone will read your bug report, and maybe will be able to help you, but it’s unlikely that it will get much attention from the team. Eventually, the issue will likely get closed in favor of issues that have reproducible demos.
+
+        Please remember that:
+
+        - Issues without reproducible demos have a very low priority.
+        - The person fixing the bug would have to do that anyway. Please be respectful of their time.
+        - You might figure out the issues yourself as you work on extracting it.
+
+        Thanks for helping us help you!
+
   - type: textarea
     attributes:
       label: Steps to reproduce
-      description: Use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
+      description: Write down the steps to reproduce the bug. You should start with a fresh installation, or your git repository linked above.
       placeholder: |
-        Write your steps here.
-
         1. Step 1...
         2. Step 2...
         3. Step 3...
@@ -55,7 +76,6 @@ body:
       required: true
 
   - type: textarea
-
     attributes:
       label: Expected behavior
       description: |
@@ -87,22 +107,6 @@ body:
         - Environment name and version (e.g. Chrome 89, Node.js 16.4):
         - Operating system and version (e.g. Ubuntu 20.04.2 LTS):
 
-  - type: input
-    attributes:
-      label: Reproducible demo
-      description: |
-        Paste the link to an example repo, including a `docusaurus.config.js`, and exact instructions to reproduce the issue. Use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
-
-        > **What happens if you skip this step?** Someone will read your bug report, and maybe will be able to help you, but it’s unlikely that it will get much attention from the team. Eventually, the issue will likely get closed in favor of issues that have reproducible demos.
-
-        Please remember that:
-
-        - Issues without reproducible demos have a very low priority.
-        - The person fixing the bug would have to do that anyway. Please be respectful of their time.
-        - You might figure out the issues yourself as you work on extracting it.
-
-        Thanks for helping us help you!
-
   - type: checkboxes
     attributes:
       label: Self-service

.github/ISSUE_TEMPLATE/documentation.yml

@@ -27,7 +27,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: textarea

.github/ISSUE_TEMPLATE/feature.yml

@@ -15,7 +15,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: textarea

.github/ISSUE_TEMPLATE/proposal.yml

@@ -23,7 +23,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: textarea

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,26 +1,44 @@
 <!--
 Thank you for sending the PR! We appreciate you spending the time to work on these changes.
-
-Help us understand your motivation by explaining why you decided to make this change.
-
 You can learn more about contributing to Docusaurus here: https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md
-
 Happy contributing!
+-->
 
+## Pre-flight checklist
+
+- [ ] I have read the [Contributing Guidelines on pull requests](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#pull-requests).
+- [ ] **If this is a code change**: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
+- [ ] **If this is a new API or substantial change**: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.
+
+<!--
+Please also remember to sign the CLA, although you can also sign it after submitting the PR. The CLA is required for us to merge your PR.
+If this PR adds or changes functionality, please take some time to update the docs. You can also write docs after the API design is finalized and the code changes have been approved.
 -->
 
 ## Motivation
 
-(Write your motivation here.)
-
-### Have you read the [Contributing Guidelines on pull requests](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#pull-requests)?
-
-(Write your answer here.)
+<!-- Help us understand your motivation by explaining why you decided to make this change. Does this fix a bug? Does it close an issue? -->
 
 ## Test Plan
 
-(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)
+<!-- Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos! -->
 
-## Related PRs
+### Test links
 
-(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)
+<!--
+🙏 Please add an exhaustive list of links relevant to this pull request.
+⏱ This saves maintainers a lot of time during reviews.
+
+- If you changed anything that's displayed on UI, please add a dogfooding page in website/_dogfooding to help us preview the effect. Those tests are deployed at https://docusaurus.io/tests
+- If you changed documentation, please link to the new and updated documentation pages.
+
+After submission, our Netlify bot will post a deploy preview link in comment, in the format of https://deploy-preview-<PR-NUMBER>--docusaurus-2.netlify.app/. Once available, please edit this section with links to the relevant deploy preview pages.
+
+Please don't be afraid to change the main site's configuration as well! You can make use of your new feature on our site so we can preview its effects. We can decide if it should be kept in production before merging it.
+-->
+
+Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/
+
+## Related issues/PRs
+
+<!-- If you haven't already, link to issues/PRs that are related to this change. This helps us develop the context and keep a rich repo history. If this PR is a continuation of a past PR's work, link to that PR. If the PR addresses part of the problem in a meta-issue, mention that issue. -->

.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: '/'
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 99
+    labels:
+      - 'pr: dependencies'
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'daily'
+    # Disable version updates for npm dependencies
+    # https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#overriding-the-default-behavior-with-a-configuration-file
+    open-pull-requests-limit: 0
+    labels:
+      - 'pr: dependencies'

.github/workflows/argos.yml

@@ -0,0 +1,48 @@
+name: Argos CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    types:
+      # Those 3 are the default PR workflow activity types,
+      # see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+      - opened
+      - synchronize
+      - reopened
+      # We want trigger workflow on labeled too!
+      - labeled
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  take-screenshots:
+    # Argos is heavy to run
+    # We only want to trigger Argos on PRs with the 'Argos' label
+    # See https://stackoverflow.com/questions/62325286/run-github-actions-when-pull-requests-have-a-specific-label
+    if: ${{ (github.event_name != 'pull_request' && github.ref_name == 'main') || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn || yarn || yarn
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Build website fast
+        run: yarn argos:build
+
+      - name: Take Argos screenshots
+        run: yarn argos:screenshot

.github/workflows/build-blog-only.yml

@@ -4,8 +4,16 @@ on:
   pull_request:
     branches:
       - main
+      - docusaurus-v**
     paths:
-      - packages/docusaurus/**
+      - packages/**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   build:
@@ -13,11 +21,16 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Build blog-only
         run: yarn workspace website build:blogOnly
+        env:
+          DOCUSAURUS_PERF_LOGGER: 'true'

.github/workflows/build-hash-router.yml

@@ -0,0 +1,84 @@
+name: Build Hash Router
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches:
+      - main
+      - docusaurus-v**
+    paths:
+      - packages/**
+      - .github/workflows/build-hash-router.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build Hash Router
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: Installation
+        run: yarn || yarn || yarn
+
+      - name: Build Hash Router
+        run: yarn build:website:fast
+        env:
+          DOCUSAURUS_PERF_LOGGER: 'true'
+          DOCUSAURUS_ROUTER: 'hash'
+          # Note: hash router + baseUrl do not play well together
+          # This would host at https://facebook.github.io/docusaurus/#/docusaurus/
+          # BASE_URL: '/docusaurus/' # hash router +
+
+      - name: Upload Website artifact
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: website-hash-router-archive
+          path: website/build
+
+      #- name: Upload Website Pages artifact
+      #  uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+      #  with:
+      #    path: website/build
+
+      # Deploy to https://facebook.github.io/docusaurus/
+      - name: Deploy to GitHub Pages
+        if: ${{ github.event_name != 'pull_request' && github.ref_name == 'main' }}
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: website/build
+
+  ## TODO we should be able to use this new deploy-pages action
+  ## However this requires a Meta admin to configure it here
+  ## https://github.com/facebook/docusaurus/settings/pages
+  ## So for now we keep using the former method
+  ## See https://docusaurus.io/docs/deployment#triggering-deployment-with-github-actions
+  #deploy:
+  #  name: Deploy to GitHub Pages
+  #  if: ${{ github.event_name != 'pull_request' && github.ref_name == 'main' }}
+  #  needs: build
+  #  permissions:
+  #    pages: write
+  #    id-token: write
+  #  environment:
+  #    name: github-pages
+  #    url: ${{ steps.deployment.outputs.page_url }}
+  #  runs-on: ubuntu-latest
+  #  steps:
+  #     - name: Deploy to GitHub Pages
+  #      id: deployment
+  #      uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/build-perf.yml

@@ -9,46 +9,95 @@ on:
   pull_request:
     branches:
       - main
-    paths-ignore:
-      - website/docs/**
+      - docusaurus-v**
+    paths:
+      - .github/workflows/build-perf.yml
+      - package.json
+      - yarn.lock
+      - packages/**
+      - website/**
+      - '!website/docs/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
+  # Posts a PR comment with build size differences from PR vs main branches
   build-size:
+    permissions:
+      checks: write # for preactjs/compressed-size-action to create and update the checks
+      contents: read # for actions/checkout to fetch code
+      issues: write # for preactjs/compressed-size-action to create comments
+      pull-requests: write # for preactjs/compressed-size-action to write a PR review
     name: Build Size Report
     timeout-minutes: 30
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
+          node-version: lts/*
           cache: yarn
-      - uses: preactjs/compressed-size-action@v2
+      - name: Track build size changes
+        uses: preactjs/compressed-size-action@8518045ed95e94e971b83333085e1cb99aa18aa8 # v2.9.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          build-script: build:website:en
-          pattern: '{website/build/assets/js/main*js,website/build/assets/css/styles*css,website/.docusaurus/globalData.json,website/build/index.html,website/build/blog/index.html,website/build/blog/**/introducing-docusaurus/*,website/build/docs/index.html,website/build/docs/installation/index.html,website/build/tests/docs/index.html,website/build/tests/docs/standalone/index.html}'
+          build-script: build:website:fast
+          clean-script: clear:website # see https://github.com/facebook/docusaurus/pull/6838
+          pattern: '{website/build/assets/js/main*js,website/build/assets/js/runtime~main*js,website/build/assets/css/styles*css,website/.docusaurus/globalData.json,website/.docusaurus/registry.js,website/.docusaurus/routes.js,website/.docusaurus/routesChunkNames.json,website/.docusaurus/site-metadata.json,website/.docusaurus/codeTranslations.json,website/.docusaurus/i18n.json,website/.docusaurus/docusaurus.config.mjs,website/build/index.html,website/build/docs.html,website/build/docs/**/*.html,website/build/blog.html,website/build/blog/**/*.html}'
+          # HTML files: exclude versioned docs pages, tags pages, html redirect files
+          exclude: '{website/build/docs/?.?.?/**/*.html,website/build/docs/next/**/*.html,website/build/blog/tags/**/*.html,**/*.html.html}'
           strip-hash: '\.([^;]\w{7})\.'
           minimum-change-threshold: 30
           compression: none
+          comment-key: DOCUSAURUS_INFRA_${{ matrix.DOCUSAURUS_INFRA }}
+        env:
+          DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
+
+  # Ensures build times stay under reasonable thresholds
   build-time:
     name: Build Time Perf
     timeout-minutes: 30
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
 
       # Ensure build with a cold cache does not increase too much
       - name: Build (cold cache)
-        run: yarn workspace website build --locale en
-        timeout-minutes: 8
+        run: yarn build:website:fast
+        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 3 || 2  }}
+        env:
+          DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
       # Ensure build with a warm cache does not increase too much
       - name: Build (warm cache)
-        run: yarn workspace website build --locale en
-        timeout-minutes: 2
-    # TODO post a Github comment with build with perf warnings?
+        run: yarn build:website:fast
+        # Temporary: upper value for Rspack until incremental cache works better
+        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 1 || 2  }}
+        env:
+          DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
+
+    # TODO post a GitHub comment with build with perf warnings?

.github/workflows/canary-release.yml

@@ -1,27 +1,32 @@
 name: Canary Release
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - main
+      - docusaurus-v**
     paths:
+      - .github/workflows/canary-release.yml
+      - package.json
       - packages/**
 
+permissions:
+  contents: read
+
 jobs:
   publish-canary:
     name: Publish Canary
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [14.x]
     steps:
-      - uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0 # Needed to get the commit number with "git rev-list --count HEAD"
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: lts/*
           cache: yarn
       - name: Prepare git
         run: |
@@ -36,7 +41,7 @@ jobs:
         env:
           NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Publish Canary release
         run: |
           yarn canary

.github/workflows/codeql-analysis.yml

@@ -4,12 +4,18 @@ on:
   push:
     branches:
       - main
+      - docusaurus-v**
   pull_request:
     branches:
       - main
+      - docusaurus-v**
   schedule:
     - cron: 25 22 * * 3
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   analyze:
     name: Analyze
@@ -26,13 +32,13 @@ jobs:
           - javascript
 
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v1
+        uses: github/codeql-action/init@4e94bd11f71e507f7f87df81788dff88d1dacbfb # 4.31.0
         with:
           languages: ${{ matrix.language }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v1
+        uses: github/codeql-action/analyze@4e94bd11f71e507f7f87df81788dff88d1dacbfb # 4.31.0

.github/workflows/continuous-releases.yml

@@ -0,0 +1,41 @@
+name: Continuous Releases
+
+on:
+  push:
+    branches:
+      - main
+      - docusaurus-v**
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: Continuous Releases
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+
+      - name: Installation
+        run: yarn || yarn || yarn
+
+      - name: Build packages
+        run: yarn build:packages
+
+      - name: Initialize fresh templates
+        run: |
+          yarn create-docusaurus template/docusaurus-classic-js classic --javascript -p npm
+          yarn create-docusaurus template/docusaurus-classic-ts classic --typescript -p npm
+
+      - name: Release
+        run: npx pkg-pr-new@0.0.20 publish './packages/*' --template './template/*' --compact --comment=off

.github/workflows/cspell-problem-matcher.json

@@ -0,0 +1,16 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "cspell",
+      "pattern": [
+        {
+          "regexp": "^(.*):(\\d+):(\\d+)\\s+\\-\\s+(.*)$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4
+        }
+      ]
+    }
+  ]
+}

.github/workflows/dependency-review.yml

@@ -0,0 +1,18 @@
+name: Dependency Review
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Dependency Review
+        uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261 # 4.8.2

.github/workflows/lighthouse-report.yml

@@ -1,61 +1,71 @@
 name: Lighthouse Report
 
 on:
-  pull_request_target:
+  pull_request:
     branches:
       - main
+      - docusaurus-v**
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
 
 jobs:
   lighthouse-report:
+    permissions:
+      pull-requests: write # for marocchino/sticky-pull-request-comment
     name: Lighthouse Report
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Wait for the Netlify Preview
-        uses: jakepartusch/wait-for-netlify-action@v1
-        id: netlify
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
-          site_name: docusaurus-2
-          max_timeout: 600
+          node-version: lts/*
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn || yarn || yarn
+
+      - name: Build website fast
+        run: yarn build:website:fast
+
       - name: Audit URLs using Lighthouse
         id: lighthouse_audit
-        uses: treosh/lighthouse-ci-action@v3
+        uses: treosh/lighthouse-ci-action@fcd65974f7c4c2bf0ee9d09b84d2489183c29726 # 12.6.1
         with:
           urls: |
-            https://deploy-preview-$PR_NUMBER--docusaurus-2.netlify.app/
-          configPath: ./.github/workflows/lighthousesrc.json
+            http://localhost:3000
+            http://localhost:3000/docs/installation
+            http://localhost:3000/docs/category/getting-started
+            http://localhost:3000/blog
+            http://localhost:3000/blog/preparing-your-site-for-docusaurus-v3
+            http://localhost:3000/blog/tags/release
+            http://localhost:3000/blog/tags
+          configPath: ./.github/workflows/lighthouserc.json
           uploadArtifacts: true
           temporaryPublicStorage: true
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number}}
+
       - name: Format lighthouse score
         id: format_lighthouse_score
-        uses: actions/github-script@v3
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # 8.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            const result = ${{ steps.lighthouse_audit.outputs.manifest }}[0].summary
+            const results = ${{ steps.lighthouse_audit.outputs.manifest }}
             const links = ${{ steps.lighthouse_audit.outputs.links }}
-            const formatResult = (res) => Math.round((res * 100))
-            Object.keys(result).forEach(key => result[key] = formatResult(result[key]))
-            const score = res => res >= 90 ? '🟢' : res >= 50 ? '🟠' : '🔴'
-            const comment = [
-                `⚡️ [Lighthouse report](${Object.values(links)[0]}) for the changes in this PR:`,
-                '| Category | Score |',
-                '| --- | --- |',
-                `| ${score(result.performance)} Performance | ${result.performance} |`,
-                `| ${score(result.accessibility)} Accessibility | ${result.accessibility} |`,
-                `| ${score(result['best-practices'])} Best practices | ${result['best-practices']} |`,
-                `| ${score(result.seo)} SEO | ${result.seo} |`,
-                `| ${score(result.pwa)} PWA | ${result.pwa} |`,
-                ' ',
-                `*Lighthouse ran on [${Object.keys(links)[0]}](${Object.keys(links)[0]})*`
-            ].join('\n')
-             core.setOutput("comment", comment);
+            const createLighthouseReport = (await import(`${process.env.GITHUB_WORKSPACE}/admin/scripts/formatLighthouseReport.js`)).default;
+            const comment = createLighthouseReport({ results, links });
+            core.setOutput("comment", comment);
 
       - name: Add Lighthouse stats as comment
         id: comment_to_pr
-        uses: marocchino/sticky-pull-request-comment@v2.0.0
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # 2.9.4
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/lighthouserc.json

@@ -0,0 +1,22 @@
+{
+  "ci": {
+    "collect": {
+      "startServerCommand": "yarn serve:website",
+      "startServerReadyPattern": "Serving",
+      "startServerReadyTimeout": 10000,
+
+      "numberOfRuns": 1,
+
+      "settings": {
+        "skipAudits": [
+          "robots-txt",
+          "canonical",
+          "tap-targets",
+          "is-crawlable",
+          "works-offline",
+          "offline-start-url"
+        ]
+      }
+    }
+  }
+}

.github/workflows/lighthousesrc.json

@@ -1,16 +0,0 @@
-{
-  "ci": {
-    "collect": {
-      "settings": {
-        "skipAudits": [
-          "robots-txt",
-          "canonical",
-          "tap-targets",
-          "is-crawlable",
-          "works-offline",
-          "offline-start-url"
-        ]
-      }
-    }
-  }
-}

.github/workflows/lint-autofix.yml

@@ -0,0 +1,47 @@
+name: Lint AutoFix
+
+on:
+  pull_request:
+    branches:
+      - main
+      - docusaurus-v**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  lint-autofix:
+    name: Lint AutoFix
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.head_ref }}
+
+      - name: Installation
+        run: yarn || yarn || yarn
+
+      - name: AutoFix Format
+        run: yarn format
+
+      - name: AutoFix JS
+        run: yarn lint:js:fix
+
+      - name: AutoFix Style
+        run: yarn lint:style:fix
+
+      - name: AutoFix Spelling
+        run: yarn lint:spelling:fix
+
+      - name: Print Diff
+        run: git diff
+
+      - uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: 'refactor: apply lint autofix'

.github/workflows/lint.yml

@@ -4,6 +4,14 @@ on:
   pull_request:
     branches:
       - main
+      - docusaurus-v**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   lint:
@@ -11,18 +19,26 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
-        # run: yarn install --immutable # Fails if yarn.lock is modified  (unfortunately only works for Yarn 2, and --frozen-lockfile is not the same!)
+        run: yarn install --frozen-lockfile || yarn install --frozen-lockfile || yarn install --frozen-lockfile
       - name: Check immutable yarn.lock
         run: git diff --exit-code
+
+      - name: Check for suspicious yarn.lock
+        # for allowed aliases, see https://github.com/yargs/cliui/pull/139/files#r1670711112
+        run: yarn lockfile-lint --path yarn.lock --type yarn --allowed-hosts yarn --validate-https --validate-package-names --validate-integrity --empty-hostname=false --allowed-package-name-aliases react-loadable react-helmet-async string-width-cjs strip-ansi-cjs wrap-ansi-cjs
+
       - name: Lint
-        run: yarn lint:ci
+        run: |
+          echo "::add-matcher::.github/workflows/cspell-problem-matcher.json"
+          yarn lint:ci
+
       - name: Prettier Code
         run: yarn format:diff
-      - name: Prettier Docs
-        run: yarn format-docs:diff

.github/workflows/showcase-test.yml

@@ -4,23 +4,31 @@ on:
   pull_request:
     branches:
       - main
+      - docusaurus-v**
     paths:
       - website/src/data/**
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   validate-config:
     name: Validate Showcase Config
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
-          node-version: ${{ matrix.node }}
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Test
         run: yarn test website/src/data/__tests__/user.test.ts
-  # TODO another job to optimize the images, see https://github.com/facebook/docusaurus/issues/5980

.github/workflows/tests-e2e.yml

@@ -4,13 +4,32 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - website/**
+      - docusaurus-v**
+    paths:
+      - package.json
+      - yarn.lock
+      - jest.config.mjs
+      - packages/**
+      - tsconfig.*.json
   pull_request:
     branches:
       - main
-    paths-ignore:
-      - website/**
+      - docusaurus-v**
+    paths:
+      - package.json
+      - yarn.lock
+      - jest.config.mjs
+      - packages/**
+      - tsconfig.*.json
+      - admin/verdaccio.yaml
+      - .github/workflows/tests-e2e.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   yarn-v1:
@@ -19,22 +38,21 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['14', '16', '17']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
-      - uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Generate test-website project against main branch
         run: yarn test:build:website -s
-        env:
-          KEEP_CONTAINER: true
       - name: Install test-website project with Yarn v1
-        run: yarn install
+        run: yarn || yarn || yarn
         working-directory: ../test-website
         env:
           npm_config_registry: http://localhost:4873
@@ -44,10 +62,57 @@ jobs:
         env:
           E2E_TEST: true
       - name: Build test-website project
-        run: yarn build
-        working-directory: ../test-website
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build --locale en --locale fr
         env:
-          CI: true
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+        working-directory: ../test-website
+
+  yarn-v1-windows:
+    name: E2E — Yarn v1 Windows
+    timeout-minutes: 30
+    runs-on: windows-8-core
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Use Node.js LTS
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: Installation
+        run: yarn || yarn || yarn
+      - name: Generate test-website project against main branch
+        # Not using test-release.sh => no verdaccio docker image on Windows
+        # run: bash ./admin/scripts/test-release.sh -s
+        run: yarn create-docusaurus test-website-in-workspace classic --typescript
+      - name: Install test-website project with Yarn v1
+        run: yarn || yarn || yarn
+        working-directory: test-website-in-workspace
+      - name: Start test-website project
+        run: yarn start --no-open
+        working-directory: test-website-in-workspace
+        env:
+          E2E_TEST: true
+      - name: Build test-website project
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+        working-directory: test-website-in-workspace
+      - name: Upload Website artifact
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: website-e2e-windows
+          path: test-website-in-workspace/build
 
   yarn-berry:
     name: E2E — Yarn Berry
@@ -55,21 +120,20 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['14']
         nodeLinker: [pnp, node-modules]
+        variant: [-s, -st]
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Use Node.js LTS
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
-          node-version: ${{ matrix.node }}
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
-      - name: Generate test-website project against main branch
-        run: yarn test:build:website -s
-        env:
-          KEEP_CONTAINER: true
+        run: yarn || yarn || yarn
+      - name: Generate test-website project with ${{ matrix.variant }} against main branch
+        run: yarn test:build:website ${{ matrix.variant }}
       - name: Install test-website project with Yarn Berry and nodeLinker = ${{ matrix.nodeLinker }}
         run: |
           yarn set version berry
@@ -79,11 +143,11 @@ jobs:
           yarn config set unsafeHttpWhitelist --json '["localhost"]'
           yarn config set enableGlobalCache true
 
-          # Patch package so that peer deps are provided. This has been fixed in terser by making acorn a direct dependency
-          # TODO watch out for the next terser release. Commit: https://github.com/terser/terser/commit/05b23eeb682d732484ad51b19bf528258fd5dc2a
-          yarn config set packageExtensions --json '{"terser-webpack-plugin@*": {"dependencies": {"acorn": "^8.6.0"}}, "html-minifier-terser@*": {"dependencies": {"acorn": "^8.6.0"}}}'
+          # Make PnP as strict as possible
+          # https://yarnpkg.com/features/pnp#fallback-mode
+          yarn config set pnpFallbackMode none
 
-          yarn install
+          yarn || yarn || yarn
         working-directory: ../test-website
         env:
           YARN_ENABLE_IMMUTABLE_INSTALLS: false # Yarn berry should create the lockfile, despite CI env
@@ -92,8 +156,115 @@ jobs:
         working-directory: ../test-website
         env:
           E2E_TEST: true
+      - name: TypeCheck website
+        # TODO: there're some lingering issues with PnP + tsc. Enable tsc in PnP later.
+        if: matrix.variant == '-st' && matrix.nodeLinker != 'pnp'
+        working-directory: ../test-website
+        run: yarn typecheck
+      - name: TypeCheck website - min version - v5.1
+        # TODO: there're some lingering issues with PnP + tsc. Enable tsc in PnP later.
+        if: matrix.variant == '-st' && matrix.nodeLinker != 'pnp'
+        working-directory: ../test-website
+        run: |
+          yarn add typescript@5.1.6 --exact
+          yarn typecheck
+      - name: TypeCheck website - max version - Latest
+        # TODO: there're some lingering issues with PnP + tsc. Enable tsc in PnP later.
+        if: matrix.variant == '-st' && matrix.nodeLinker != 'pnp'
+        working-directory: ../test-website
+        run: |
+          yarn add typescript@latest --exact
+          yarn typecheck
+
       - name: Build test-website project
-        run: yarn build
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+        working-directory: ../test-website
+
+  npm:
+    name: E2E — npm
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Use Node.js LTS
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: Installation
+        run: yarn || yarn || yarn
+      - name: Generate test-website project against main branch
+        run: yarn test:build:website -st
+      - name: Install test-website project with npm
+        run: npm install
         working-directory: ../test-website
         env:
-          CI: true
+          npm_config_registry: http://localhost:4873
+      - name: TypeCheck website
+        working-directory: ../test-website
+        run: yarn typecheck
+      - name: Start test-website project
+        run: npm run start -- --no-open
+        working-directory: ../test-website
+        env:
+          E2E_TEST: true
+      - name: Build test-website project
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: npm run build -- --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+        working-directory: ../test-website
+
+  pnpm:
+    name: E2E — pnpm
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Use Node.js LTS
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: Installation
+        run: yarn || yarn || yarn
+      - name: Generate test-website project against main branch
+        run: yarn test:build:website -st
+      - name: Install test-website project with pnpm
+        run: |
+          npm install -g pnpm
+          pnpm install
+        working-directory: ../test-website
+        env:
+          npm_config_registry: http://localhost:4873
+      - name: TypeCheck website
+        working-directory: ../test-website
+        run: yarn typecheck
+      - name: Start test-website project
+        run: pnpm start --no-open
+        working-directory: ../test-website
+        env:
+          E2E_TEST: true
+      - name: Build test-website project
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: pnpm run build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+        working-directory: ../test-website

.github/workflows/tests-swizzle.yml

@@ -0,0 +1,46 @@
+name: Swizzle Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+      - docusaurus-v**
+    paths:
+      - packages/**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Swizzle
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        action: ['eject', 'wrap']
+        variant: ['js', 'ts']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Set up Node LTS
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: Installation
+        run: yarn || yarn || yarn
+
+      # Swizzle all the theme components
+      - name: Swizzle (${{matrix.action}} - ${{matrix.variant}})
+        run: yarn workspace website test:swizzle:${{matrix.action}}:${{matrix.variant}}
+      # Build swizzled site
+      - name: Build website
+        run: yarn build:website:fast
+      # Ensure swizzled site still typechecks
+      - name: TypeCheck website
+        run: yarn workspace website typecheck --project tsconfig.skipLibCheck.json

.github/workflows/tests-windows.yml

@@ -4,8 +4,21 @@ on:
   pull_request:
     branches:
       - main
-    paths-ignore:
-      - website/**
+      - docusaurus-v**
+    paths:
+      - package.json
+      - yarn.lock
+      - jest.config.mjs
+      - packages/**
+      - tsconfig.*.json
+      - .github/workflows/tests-windows.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   windows-test:
@@ -14,17 +27,19 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        node: ['14', '16', '17']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Support longpaths
         run: git config --system core.longpaths true
-      - uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
+          cache: yarn
       - name: Installation
-        run: yarn || yarn || yarn # 3 attempts to avoid timeout errors...
+        run: yarn || yarn || yarn
       - name: Docusaurus Jest Tests
         run: yarn test
       - name: Create a deep path
@@ -34,7 +49,29 @@ jobs:
           mkdir -p "website/_dogfooding/_pages tests/deep-file-path-test/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar"
           cd "$_"
           echo "# hello" > test-file.md
+      # Lightweight version of tests-swizzle.yml workflow, but for Windows
+      - name: Swizzle Wrap TS
+        run: yarn workspace website test:swizzle:wrap:ts
       - name: Docusaurus Build
-        run: yarn build:website --locale en
+        run: yarn build:website:fast
         env:
-          CI: true
+          DOCUSAURUS_PERF_LOGGER: 'true'
+
+      - name: TypeCheck website
+        # see https://github.com/facebook/docusaurus/pull/10486
+        run: yarn workspace website typecheck
+      - name: TypeCheck website - min version - v5.1
+        run: |
+          yarn add typescript@5.1.6 --exact -D -W --ignore-scripts
+
+          # DocSearch@4/ai@5 doesn't support TS 5.1 (with skipLibCheck=false)
+          jq '.resolutions."@docsearch/react" = "^3.9.0"' package.json > package.json.tmp && mv -Force package.json.tmp package.json
+          yarn add @docsearch/react@^3.9.0 --exact -D -W --ignore-scripts
+
+          yarn workspace website typecheck
+      - name: TypeCheck website - max version - Latest
+        # For latest TS there are often lib check errors, so we disable it
+        # Details: https://github.com/facebook/docusaurus/pull/10486
+        run: |
+          yarn add typescript@latest --exact -D -W --ignore-scripts
+          yarn workspace website typecheck --project tsconfig.skipLibCheck.json

.github/workflows/tests.yml

@@ -4,8 +4,21 @@ on:
   pull_request:
     branches:
       - main
-    paths-ignore:
-      - website/**
+      - docusaurus-v**
+    paths:
+      - package.json
+      - yarn.lock
+      - jest.config.mjs
+      - packages/**
+      - tsconfig.*.json
+      - .github/workflows/tests.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
   test:
@@ -14,17 +27,48 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['14', '16', '17']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
-      - uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Test
         run: yarn test
+      - name: Remove Theme Internal Re-export
+        run: yarn workspace @docusaurus/theme-common removeThemeInternalReexport
+      - name: Docusaurus Build
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build:website:fast --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=450'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+      - name: Docusaurus site CSS order
+        run: yarn workspace website test:css-order
+
       - name: TypeCheck website
-        run: yarn workspace website tsc
+        # see https://github.com/facebook/docusaurus/pull/10486
+        run: yarn workspace website typecheck
+      - name: TypeCheck website - min version - v5.1
+        run: |
+          yarn add typescript@5.1.6 --exact -D -W --ignore-scripts
+
+          # DocSearch@4/ai@5 doesn't support TS 5.1 (with skipLibCheck=false)
+          jq '.resolutions."@docsearch/react" = "^3.9.0"' package.json > package.json.tmp && mv -f package.json.tmp package.json
+          yarn add @docsearch/react@^3.9.0 --exact -D -W --ignore-scripts
+
+          yarn workspace website typecheck
+      - name: TypeCheck website - max version - Latest
+        # For latest TS there are often lib check errors, so we disable it
+        # Details: https://github.com/facebook/docusaurus/pull/10486
+        run: |
+          yarn add typescript@latest --exact -D -W --ignore-scripts
+          yarn workspace website typecheck --project tsconfig.skipLibCheck.json

.gitignore

@@ -1,17 +1,20 @@
 .DS_Store
-.vscode
+.vscode/*
+!.vscode/extensions.json
 .idea
 *.iml
 *.code-workspace
 .changelog
+.history
 
 node_modules
 .yarn
+package-lock.json
 
 .eslintcache
 
 yarn-error.log
-build
+website/build
 coverage
 .docusaurus
 .cache-loader
@@ -23,14 +26,29 @@ packages/create-docusaurus/lib/
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*
-packages/docusaurus-*/lib-next/
+packages/eslint-plugin/lib/
+packages/stylelint-copyright/lib/
 
 website/netlifyDeployPreview/*
+website/changelog
 !website/netlifyDeployPreview/index.html
 !website/netlifyDeployPreview/_redirects
 
+website/_dogfooding/_swizzle_theme_tests
+
+CrowdinTranslations_*.zip
+
+website/.cpu-prof
+
 website/i18n/**/*
 #!website/i18n/fr
 #!website/i18n/fr/**/*
 
 .netlify
+
+website/rspack-tracing.json
+website/rspack-tracing.pftrace
+website/bundler-cpu-profile.json
+website/profile.json.gz
+
+

.husky/pre-commit

@@ -1,4 +1,7 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-yarn lint-staged --allow-empty
+# Workaround of a mysterious bug in either lint-staged or husky.
+# https://github.com/typicode/husky/issues/1134
+# https://github.com/okonet/lint-staged/issues/693#issuecomment-1079759224
+FORCE_COLOR=1 yarn lint-staged --allow-empty

.lintstagedrc.json

@@ -0,0 +1,5 @@
+{
+  "*.{js,jsx,ts,tsx,mjs}": ["eslint --fix"],
+  "*.css": ["stylelint --allow-empty-input --fix"],
+  "*": ["prettier --ignore-unknown --write"]
+}

.nvmrc

@@ -1 +1 @@
-14.16.0
+22

.prettierignore

@@ -1,19 +1,36 @@
 dist
 node_modules
 .yarn
-build
+**/build/**
 coverage
 .docusaurus
+.idea
+
+.svg
+*.svg
+
+jest/vendor
+
+argos/test-results
+
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*
-packages/docusaurus-*/lib-next/
 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/*/docusaurus.config.js
+packages/eslint-plugin/lib/
+packages/stylelint-copyright/lib/
 __fixtures__
 
 website/i18n
 website/versions.json
 website/docusaurus.config.js
+website/versioned_sidebars/*.json
 
 examples/
+website/static/katex/katex.min.css
+
+website/changelog
+website/_dogfooding/_swizzle_theme_tests
+website/_dogfooding/_asset-tests/badSyntax.js
+website/_dogfooding/_asset-tests/badSyntax.css

.stylelintignore

@@ -1,2 +1,18 @@
+# Stylelint runs on everything by default; we only lint CSS files.
+*
+!*/
+!*.css
+__tests__/
+build
+coverage
+examples/
+
+packages/lqip-loader/lib/
+packages/docusaurus/lib/
+packages/docusaurus-*/lib/*
+packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/
-examples
+website/static/katex/katex.min.css
+website/_dogfooding/_asset-tests/badSyntax.css
+
+jest/vendor

.stylelintrc.js

@@ -6,8 +6,31 @@
  */
 
 module.exports = {
+  extends: ['stylelint-config-standard', 'stylelint-config-prettier'],
   plugins: ['stylelint-copyright'],
   rules: {
-    'docusaurus/copyright-header': true,
+    'docusaurus/copyright-header': [
+      true,
+      {
+        header: `*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.`,
+      },
+    ],
+    'selector-pseudo-class-no-unknown': [
+      true,
+      {
+        // :global is a CSS modules feature to escape from class name hashing
+        ignorePseudoClasses: ['global'],
+      },
+    ],
+    'selector-class-pattern': null,
+    'custom-property-empty-line-before': null,
+    'selector-id-pattern': null,
+    'declaration-empty-line-before': null,
+    'comment-empty-line-before': null,
+    'value-keyword-case': ['lower', {camelCaseSvgKeywords: true}],
   },
 };

.vscode/extensions.json

@@ -0,0 +1,12 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+  "recommendations": [
+    "streetsidesoftware.code-spell-checker",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "stylelint.vscode-stylelint",
+    "EditorConfig.EditorConfig",
+    "Gruntfuggly.todo-tree"
+  ],
+  "unwantedRecommendations": []
+}

CODE_OF_CONDUCT.md

@@ -1,3 +1,3 @@
 # Code of Conduct
 
-Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.fb.com/codeofconduct/) so that you can understand what actions will and will not be tolerated.
+Meta has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.fb.com/codeofconduct/) so that you can understand what actions will and will not be tolerated.

CONTRIBUTING.md

@@ -1,31 +1,31 @@
 # Contributing to Docusaurus
 
-[Docusaurus](https://docusaurus.io) is our way to hopefully help to create open source documentation easier. We currently have [multiple open source projects using it](https://docusaurus.io/showcase), with many more planned. If you're interested in contributing to Docusaurus, hopefully, this document makes the process for contributing clear.
+[Docusaurus](https://docusaurus.io) is our way to hopefully help make open source documentation easier. We currently have [multiple open source projects using it](https://docusaurus.io/showcase), with many more planned. If you're interested in contributing to Docusaurus, hopefully, this document makes the process for contributing clear.
 
 The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
 - [Building Welcoming Communities](https://opensource.guide/building-community/)
 
-## [Code of Conduct](https://code.fb.com/codeofconduct)
+## Code of Conduct
 
-Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
+Meta has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
 
 ## Get Involved
 
 There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:
 
-- Simply start using Docusaurus. Go through the [Getting Started](https://docusaurus.io/docs/installation) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
+- Simply start using Docusaurus. Go through the [Getting Started](https://docusaurus.io/docs/installation) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#issues).
 - Look through the [open issues](https://github.com/facebook/docusaurus/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](#triaging-issues-and-pull-requests).
-- If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started.
+- If you find an issue you would like to fix, [open a pull request](#pull-requests). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started.
 - Read through the [Docusaurus docs](https://docusaurus.io/docs/installation). If you find anything that is confusing or can be improved, you can click "Edit this page" at the bottom of most docs, which takes you to the GitHub interface to make and propose changes.
 - Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/feature) by others in the community and consider opening a pull request if you see something you want to work on.
 
-Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
+Contributions are very welcome. If you think you need help planning your contribution, please ping us on X at [@docusaurus](https://x.com/docusaurus) and let us know you are looking for a bit of help.
 
 ### Join our Discord Channel
 
-We have the [`#contributors`](https://discord.gg/6g6ASPA) channel on [Discord](https://discord.gg/docusaurus) to discuss all things about Docusaurus development. You can also be of great help by helping other users in the help channel.
+We have the [`#contributors`](https://discord.gg/6g6ASPA) channel on [Discord](https://discord.gg/docusaurus) to discuss all things about Docusaurus development. You can also be of great help by helping other users in the [`#help-and-questions`](https://discord.gg/fwbcrQ3dHR) channel.
 
 ### Triaging Issues and Pull Requests
 
@@ -46,65 +46,51 @@ All pull requests will be checked by the continuous integration system, GitHub a
 
 Docusaurus has one primary branch `main` and we use feature branches with deploy previews to deliver new features with pull requests.
 
-## Proposing a Change
+## Issues
 
-If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with the [feature template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=feature%2Cneeds+triage&template=feature.yml).
+When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not being managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
 
-If you intend to change the public API (e.g., something in `siteConfig.js`) or make any non-trivial changes to the implementation, we recommend filing an issue with the [proposal template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=proposal%2Cneeds+triage&template=proposal.yml). This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.
+**Please don't use the GitHub issue tracker for questions.** If you have questions about using Docusaurus, use any of our [support channels](https://docusaurus.io/community/support), and we will do our best to answer your questions.
 
-If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend [filing an issue](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=bug%2Cneeds+triage&template=bug.yml) detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
+### Bugs
 
-### Reporting New Issues
-
-When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
+We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=bug%2Cstatus%3A+needs+triage&template=bug.yml).
 
 - **One issue, one bug:** Please report a single bug per issue.
 - **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
 
-### Bugs
-
-We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
-
-If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions.
-
-You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature%20request). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/main/.github/ISSUE_TEMPLATE/feature.md)
+If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend filing an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
 
 ### Security Bugs
 
-Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
+Meta has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
 
-## Pull Requests
+### Feature requests
 
-### Your First Pull Request
+If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can file an issue with the [feature template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=feature%2Cstatus%3A+needs+triage&template=feature.yml) in the form of an **elaborated RFC**. Alternatively, you can use the [Canny board](https://docusaurus.io/feature-requests) for more casual feature requests and gain enough traction before proposing an RFC.
 
-So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
+### Proposals
 
-Working on your first Pull Request? You can learn how from this free video series:
+If you intend to make any non-trivial changes to existing implementations, we recommend filing an issue with the [proposal template](https://github.com/facebook/docusaurus/issues/new?assignees=&labels=proposal%2Cstatus%3A+needs+triage&template=proposal.yml). This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.
 
-[**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
+### Claiming issues
 
-We have a list of [beginner friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.
+We have a list of [beginner-friendly issues](https://github.com/facebook/docusaurus/labels/good%20first%20issue) to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.
 
-### Versioned Docs
+Apart from the `good first issue`, the following labels are also worth looking at:
 
-If you only want to make content changes you just need to be aware of versioned docs.
+- [`help wanted`](https://github.com/facebook/docusaurus/labels/help%20wanted): if you have specific knowledge in one domain, working on these issues can make your expertise shine.
+- [`status: accepting pr`](https://github.com/facebook/docusaurus/labels/status%3A%20accepting%20pr): community contributors can feel free to claim any of these.
 
-- `website/docs` - The files in here are responsible for the "next" version at https://docusaurus.io/docs/next/installation.
-- `website/versioned_docs/version-X.Y.Z` - These are the docs for the X.Y.Z version at https://docusaurus.io/docs/X.Y.Z/installation.
+If you want to work on any of these issues, just drop a message saying "I am working on this". **You do not need to ask for assignment to work on any issue explicitly marked as welcoming external contributions.** However, don't "cookie lick", or squat on an issue without actually sending a PR. You are automatically considered as giving up if you don't **send a PR within seven days after your comment**, and the issue automatically becomes up for grabs again.
 
-To make a fix to the published versions you must edit the corresponding markdown file in both folders. If you only made changes in `docs`, be sure to be viewing the `next` version to see the updates (ensure there's `next` in the URL).
+Alternatively, when opening an issue, you can also click the "self service" checkbox to indicate that you'd like to work on the issue yourself, which will also make us see the issue as "claimed".
 
-> Do not edit the auto-generated files within `versioned_docs/` or `versioned_sidebars/` unless you are sure it is necessary. For example, information about new features should not be documented in versioned docs. Edits made to older versions will not be propagated to newer versions of the docs.
-
-### Installation
-
-1. Ensure you have [Yarn](https://yarnpkg.com/) installed.
-1. After cloning the repository, run `yarn install` in the root of the repository.
-1. To start a development server, run `yarn workspace website start`.
+## Development
 
 ### Online one-click setup for contributing
 
-You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click it will launch a workspace (for Docusaurus 2) and automatically:
+You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click, it will launch a workspace (for Docusaurus 2) and automatically:
 
 - clone the docusaurus repo.
 - install the dependencies.
@@ -116,76 +102,41 @@ So that you can start contributing straight away.
 
 You can also try using the new [github.dev](https://github.dev/facebook/docusaurus) feature. While you are browsing any file, changing the domain name from `github.com` to `github.dev` will turn your browser into an online editor. You can start making changes and send pull requests right away.
 
-### Sending a Pull Request
+### Installation
 
-Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages).
+1. Ensure you have [Yarn](https://yarnpkg.com/) installed.
+2. After cloning the repository, run `yarn install` in the root of the repository. This will install all dependencies as well as build all local packages.
+3. To start a development server, run `yarn workspace website start`.
+
+### Code Conventions
+
+- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation, etc.
+- "Attractive"
+- We do have Prettier (a formatter) and ESLint (a syntax linter) to catch most stylistic problems. If you are working locally, they should automatically fix some issues during every git commit.
+- **For documentation**: Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation.
+
+Don't worry too much about styles in general—the maintainers will help you fix them as they review your code.
+
+## Pull Requests
+
+So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
+
+Working on your first Pull Request? You can learn how from this free video series:
+
+[**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
 
 Please make sure the following is done when submitting a pull request:
 
-1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `main`.
-1. Add the [copyright notice](#copyright-header-for-source-code) notice to the top of any code new files you've added.
-1. Describe your [**test plan**](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/main/admin/testing-changes-on-Docusaurus-itself.md)!
-1. Make sure your code lints (`yarn prettier && yarn lint`).
-1. Make sure your Jest tests pass (`yarn test`).
-1. If you haven't already, [sign the CLA](https://code.facebook.com/cla).
+1. **Keep your PR small.** Small pull requests (~300 lines of diff) are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it.
+2. **Use descriptive titles.** It is recommended to follow this [commit message style](#semantic-commit-messages).
+3. **Test your changes.** Describe your [**test plan**](#test-plan) in your pull request description.
+4. **CLA.** If you haven't already, [sign the CLA](https://code.facebook.com/cla).
 
 All pull requests should be opened against the `main` branch.
 
-#### Test Plan
+We have a lot of integration systems that run automated tests to guard against mistakes. The maintainers will also review your code and fix obvious issues for you. These systems' duty is to make you worry as little about the chores as possible. Your code contributions are more important than sticking to any procedures, although completing the checklist will surely save everyone's time.
 
-A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI.
-
-- If you've changed APIs, update the documentation.
-
-If you need help testing your changes locally, you can check out the doc on doing [local third party testing](https://github.com/facebook/docusaurus/blob/main/admin/local-third-party-project-testing.md).
-
-#### Breaking Changes
-
-When adding a new breaking change, follow this template in your pull request:
-
-```md
-### New breaking change here
-
-- **Who does this affect**:
-- **How to migrate**:
-- **Why make this breaking change**:
-- **Severity (number of people affected x effort)**:
-```
-
-#### Copyright Header for Source Code
-
-Copy and paste this to the top of your new file(s):
-
-```js
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-```
-
-#### Contributor License Agreement (CLA)
-
-In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
-
-After you have signed the CLA, the CLA bot would automatically update the PR status. There's no need to open a new PR.
-
-**CLAs are required for us to merge your pull request.** While we value your effort and are willing to wait for you to come back and address the reviews in case you are unavailable after sending the pull request, pull requests that are ready to merge but have CLA missing and no response from the author **will be closed within two weeks of opening**. If you have further questions about the CLA, please stay in touch with us.
-
-If it happens that you were unavailable and your PR gets closed, feel free to reopen once it's ready! We are still happy to review it, help you complete it, and eventually merge it.
-
-### What Happens Next?
-
-The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
-
-## Style Guide
-
-[Prettier](https://prettier.io) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `yarn prettier`.
-
-However, there are still some styles that Prettier cannot pick up.
-
-## Semantic Commit Messages
+### Semantic Commit Messages
 
 See how a minor change to your commit message style can make you a better programmer.
 
@@ -203,35 +154,93 @@ The various types of commits:
 - `chore`: upgrading dependencies, releasing new versions... Chores that are **regularly done** for maintenance purposes.
 - `misc`: anything else that doesn't change production code, yet is not `test` or `chore`. e.g. updating GitHub actions workflow.
 
-Do not get too stressed about PR titles, however. The maintainers will help you get them right, and we also have a PR label system that doesn't equate with the commit message types. Your code is more important than conventions!
+Do not get too stressed about PR titles, however. Your PR will be squash-merged and your commit to the `main` branch will get the title of your PR, so commits within a branch don't need to be semantically named. The maintainers will help you get the PR title right, and we also have a PR label system that doesn't equate with the commit message types. Your code is more important than conventions!
 
-### Example
+Example:
 
 ```
 feat(core): allow overriding of webpack config
 ^--^^----^  ^------------^
 |   |       |
-|   |       +-> Summary in present tense.
+|   |       +-> Summary in present tense. Use lower case not title case!
 |   |
 |   +-> The package(s) that this change affected.
 |
-+-------> Type: see below for the list we use.
++-------> Type: see above for the list we use.
 ```
 
-Use lower case not title case!
+### Versioned Docs
 
-## Code Conventions
+If you only want to make doc changes, you just need to be aware of versioned docs.
 
-### General
+- `website/docs` - The files here are responsible for the "next" version at https://docusaurus.io/docs/next/installation.
+- `website/versioned_docs/version-X.Y.Z` - These are the docs for the X.Y.Z version at https://docusaurus.io/docs/X.Y.Z/installation.
 
-- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation.
-- "Attractive"
-- We do have Prettier (a formatter) and ESLint (a syntax linter) to catch most stylistic problems. If you are working locally, they should automatically fix some issues during every git commit.
+Do not edit the auto-generated files within `versioned_docs/` or `versioned_sidebars/` unless you are sure it is necessary. For example, information about new features should not be documented in versioned docs. Edits made to older versions will not be propagated to newer versions of the docs.
 
-### Documentation
+### Test Plan
 
-- Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation.
+A good test plan has the exact commands you ran and their output and provides screenshots or videos if the pull request changes UI. If you've changed APIs, update the documentation.
 
-## License
+Tests are integrated into our continuous integration system, so you don't always need to run local tests. However, for significant code changes, it saves both your and the maintainers' time if you can do exhaustive tests locally first to make sure your PR is in good shape. There are many types of tests:
 
-By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license.
+- **Build and typecheck.** We use TypeScript in our codebase, which can make sure your code is consistent and catches some obvious mistakes early.
+- **Unit tests.** We use [Jest](https://jestjs.io/) for unit tests of API endpoints' behavior. You can run `yarn test` in the root directory to run all tests, or `yarn test path/to/your/file.test.ts` to run a specific test.
+- **Dogfooding.** Our website itself covers all kinds of potential configuration cases and we even have a dedicated [tests area](https://docusaurus.io/tests). Don't be afraid to update our website's configuration in your PR—it can help the maintainers preview the effects. We can decide if the website change should be kept when merging and deploying for production.
+- **E2E tests.** You can simulate the distribution and installation of the code with your fresh changes. If you need help testing your changes locally, you can check out the doc on doing [local third-party testing](https://github.com/facebook/docusaurus/blob/main/admin/local-third-party-project-testing.md).
+
+### Licensing
+
+By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license. Copy and paste this to the top of your new file(s):
+
+```js
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+```
+
+This is also auto-fixable with the `header/header` ESLint rule.
+
+### Contributor License Agreement (CLA)
+
+In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Meta open source project, you're good to go. If you are submitting a pull request for the first time, the Meta GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
+
+After you have signed the CLA, the CLA bot would automatically update the PR status. There's no need to open a new PR.
+
+**CLAs are required for us to merge your pull request.** While we value your effort and are willing to wait for you to come back and address the reviews in case you are unavailable after sending the pull request, pull requests that are ready to merge but have CLA missing and no response from the author **will be closed within two weeks of opening**. If you have further questions about the CLA, please stay in touch with us.
+
+If it happens that you were unavailable and your PR gets closed, feel free to reopen once it's ready! We are still happy to review it, help you complete it, and eventually merge it.
+
+### AI-assisted PRs
+
+We welcome the use of AI tools for authoring PRs, and we love to see people pushing the boundaries of AI capabilities. The core team actively uses different AI tools in our development process. However, we are aware that **many people are sending entirely AI-generated PRs as a low-effort way to farm OSS contributions**, so please be mindful of the following etiquette to show your respect for our time and our codebase:
+
+- **Be transparent**: If a significant portion of your code is AI generated, please indicate that in your PR description.
+- **Be accountable**: You are responsible for the code you submit, regardless of whether it was generated by AI or written by you. You should be able to explain every line of the code, ensure all tests pass, and address our reviews.
+- **Be reasonable**: Sometimes we receive 1k LOC PRs that are obviously AI-generated and implement unsolicited features. Please note that significant changes require prior communication and approval from the team in the form of an issue.
+
+We retain the right to close any PR that we deem as unproductive or low-effort, even when we agree with the spirit of the change.
+
+### Breaking Changes
+
+When adding a new breaking change, follow this template in your pull request:
+
+```md
+### New breaking change here
+
+- **Who does this affect**:
+- **How to migrate**:
+- **Why make this breaking change**:
+- **Severity (number of people affected x effort)**:
+```
+
+> [!NOTE]
+>
+> Breaking changes should be discussed in the issue tracker before being implemented.
+
+### What Happens Next?
+
+The core Docusaurus team will be monitoring pull requests. Do help us by keeping pull requests consistent by following the guidelines above.

README.md

@@ -1,28 +1,32 @@
-<h1 align="center">
-  <p align="center">Docusaurus</p>
-  <a href="https://docusaurus.io"><img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus"></a>
-</h1>
+<div align="center">
+  <h1 align="center">
+    Docusaurus
+    <br />
+    <br />
+    <a href="https://docusaurus.io">
+      <img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus">
+    </a>
+  </h1>
+</div>
 
 <p align="center">
-  <a href="https://twitter.com/docusaurus"><img src="https://img.shields.io/twitter/follow/docusaurus.svg?style=social" align="right" alt="Twitter Follow" /></a>
+  <a href="https://x.com/docusaurus"><img src="https://img.shields.io/twitter/follow/docusaurus.svg?style=social" align="right" alt="Twitter Follow" /></a>
   <a href="#backers" alt="sponsors on Open Collective"><img src="https://opencollective.com/Docusaurus/backers/badge.svg" /></a>
   <a href="#sponsors" alt="Sponsors on Open Collective"><img src="https://opencollective.com/Docusaurus/sponsors/badge.svg" /></a>
   <a href="https://www.npmjs.com/package/@docusaurus/core"><img src="https://img.shields.io/npm/v/@docusaurus/core.svg?style=flat" alt="npm version"></a>
-  <a href="https://github.com/facebook/docusaurus/actions/workflows/tests.yml"><img src="https://github.com/facebook/docusaurus/actions/workflows/tests.yml/badge.svg" alt="Github Actions status"></a>
+  <a href="https://github.com/facebook/docusaurus/actions/workflows/tests.yml"><img src="https://github.com/facebook/docusaurus/actions/workflows/tests.yml/badge.svg" alt="GitHub Actions status"></a>
   <a href="CONTRIBUTING.md#pull-requests"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
   <a href="https://discord.gg/docusaurus"><img src="https://img.shields.io/discord/102860784329052160.svg" align="right" alt="Discord Chat" /></a>
   <a href= "https://github.com/prettier/prettier"><img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg"></a>
   <a href="#license"><img src="https://img.shields.io/github/license/sourcerer-io/hall-of-fame.svg?colorB=ff0000"></a>
   <a href="https://github.com/facebook/jest"><img src="https://img.shields.io/badge/tested_with-jest-99424f.svg" alt="Tested with Jest"></a>
+  <a href="https://argos-ci.com" target="_blank" rel="noreferrer noopener" aria-label="Covered by Argos"><img src="https://argos-ci.com/badge.svg" alt="Covered by Argos" width="133" height="20" /></a>
   <a href="https://gitpod.io/#https://github.com/facebook/docusaurus"><img src="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod" alt="Gitpod Ready-to-Code"/></a>
   <a href="https://app.netlify.com/sites/docusaurus-2/deploys"><img src="https://api.netlify.com/api/v1/badges/9e1ff559-4405-4ebe-8718-5e21c0774bc8/deploy-status" alt="Netlify Status"></a>
-  <a href="https://meercode.io/facebook/docusaurus"><img src="https://meercode.io/badge/facebook/docusaurus?type=ci-score" alt="CI Score"></a>
+  <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Ffacebook%2Fdocusaurus%2Ftree%2Fmain%2Fexamples%2Fclassic&project-name=my-docusaurus-site&repo-name=my-docusaurus-site"><img src="https://vercel.com/button" alt="Deploy with Vercel"/></a>
+  <a href="https://app.netlify.com/start/deploy?repository=https://github.com/slorber/docusaurus-starter"><img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify"></a>
 </p>
 
-> **We are working hard on Docusaurus v2. If you are new to Docusaurus, try using the new version instead of v1. See the [Docusaurus v2 website](https://docusaurus.io/) for more details.**
-
-> Docusaurus v1 doc is available at [v1.docusaurus.io](https://v1.docusaurus.io) and code is available on branch [docusaurus-v1](https://github.com/facebook/docusaurus/tree/docusaurus-v1)
-
 ## Introduction
 
 Docusaurus is a project for building, deploying, and maintaining open source project websites easily.
@@ -41,29 +45,25 @@ Short on time? Check out our [5-minute tutorial ⏱️](https://tutorial.docusau
 
 - **Customizable**
 
-> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/blog), and additional support pages, it is also [customizable](https://docusaurus.io/docs/creating-pages) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/styling-layout).
+> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/blog), and additional support pages, it is also [customizable](https://docusaurus.io/docs/creating-pages) to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/styling-layout).
 
 ## Installation
 
-Use the initialization cli to create your site:
+Use the initialization CLI to create your site:
 
 ```bash
-npm init docusaurus@latest [name] [template]
+npm init docusaurus@latest
 ```
 
-Example:
-
-```bash
-npm init docusaurus@latest my-website classic
-```
+[Read the docs](https://docusaurus.io/docs/installation) for any further information.
 
 ## Contributing
 
-We've released Docusaurus because it helps us better scale and supports the many OSS projects at Facebook. We hope that other organizations can benefit from the project. We are thankful for any contributions from the community.
+We've released Docusaurus because it helps us better scale and supports the many OSS projects at Meta. We hope that other organizations can benefit from the project. We are thankful for any contributions from the community.
 
 ### [Code of Conduct](https://code.fb.com/codeofconduct)
 
-Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
+Meta has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
 
 ### Contributing guide
 
@@ -80,7 +80,7 @@ We have a few channels for contact:
 - [Discord](https://discord.gg/docusaurus):
   - `#general` for those using Docusaurus.
   - `#contributors` for those wanting to contribute to the Docusaurus core.
-- [@docusaurus](https://twitter.com/docusaurus) on Twitter
+- [@docusaurus](https://x.com/docusaurus) X
 - [GitHub Issues](https://github.com/facebook/docusaurus/issues)
 
 ## Contributors
@@ -107,10 +107,17 @@ The Docusaurus documentation (e.g., `.md` files in the `/docs` folder) is [Creat
 
 ## Special thanks
 
-[![BrowserStack logo](./admin/img/browserstack-logo.png)](http://www.browserstack.com/)
+<p>
+  <a href="http://www.browserstack.com/" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./admin/img/browserstack-dark-mode-logo.svg#gh-dark-mode-only">
+      <img alt="BrowserStack logo" src="./admin/img/browserstack-light-mode-logo.svg#gh-light-mode-only" height="50px" />
+    </picture>
+  </a>
+</p>
 
 [BrowserStack](http://www.browserstack.com/) supports us with [free access for open source](https://www.browserstack.com/open-source).
 
 [![Rocket Validator logo](./admin/img/rocketvalidator-logo.png)](https://rocketvalidator.com/)
 
-[Rocket Validator](https://rocketvalidator.com/) helps us find HTML markup or accessibility issues.
+[Rocket Validator](https://rocketvalidator.com/) helps us find [HTML markup and accessibility issues](https://rocketvalidator.com/stats/docusaurus.io).

__tests__/validate-package-json.test.ts

@@ -5,70 +5,81 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import util from 'util';
-import globCb from 'glob';
-import fsCb from 'fs';
-
-const glob = util.promisify(globCb);
-const readFile = util.promisify(fsCb.readFile);
+import fs from 'fs-extra';
+import {Globby} from '@docusaurus/utils';
 
 type PackageJsonFile = {
   file: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  content: any;
+  content: {
+    name?: string;
+    private?: boolean;
+    version?: string;
+    repository?: {
+      type?: string;
+      url?: string;
+      directory?: string;
+    };
+    publishConfig?: {
+      access?: string;
+    };
+  };
 };
 
 async function getPackagesJsonFiles(): Promise<PackageJsonFile[]> {
-  const files = await glob('packages/*/package.json');
-
+  const files = await Globby('packages/*/package.json');
   return Promise.all(
-    files.map(async (file) => ({
-      file,
-      content: JSON.parse(await readFile(file, 'utf8')),
-    })),
+    files.map((file) =>
+      fs
+        .readJSON(file)
+        .then((content: PackageJsonFile['content']) => ({file, content})),
+    ),
   );
 }
 
 describe('packages', () => {
-  test('should be found', async () => {
+  it('are found', async () => {
     const packageJsonFiles = await getPackagesJsonFiles();
     expect(packageJsonFiles.length).toBeGreaterThan(0);
   });
 
-  test('should contain repository and directory for every package', async () => {
+  it('contain repository and directory', async () => {
     const packageJsonFiles = await getPackagesJsonFiles();
 
-    packageJsonFiles.forEach((packageJsonFile) => {
-      if (packageJsonFile.content.private !== true) {
+    packageJsonFiles
+      .filter((packageJsonFile) => !packageJsonFile.content.private)
+      .forEach((packageJsonFile) => {
         expect(packageJsonFile.content.repository).toEqual({
           type: 'git',
           url: 'https://github.com/facebook/docusaurus.git',
           directory: packageJsonFile.file.replace(/\/package\.json$/, ''),
         });
-      }
-    });
+      });
   });
 
   /*
   If a package starts with @, if won't be published to public npm registry
-  without an additional publishConfig.acces: "public" config
+  without an additional publishConfig.access: "public" config
   This will make you publish an incomplete list of Docusaurus packages
   when trying to release with lerna-publish
    */
-  test('should have publishConfig.access: "public" when name starts with @', async () => {
+  it('have publishConfig.access: "public" when name starts with @', async () => {
     const packageJsonFiles = await getPackagesJsonFiles();
 
-    packageJsonFiles.forEach((packageJsonFile) => {
-      if (packageJsonFile.content.name.startsWith('@')) {
-        // Unfortunately jest custom message do not exist in loops, so using an exception instead to show failing package file
+    packageJsonFiles
+      .filter((packageJsonFile) =>
+        packageJsonFile.content.name?.startsWith('@'),
+      )
+      .forEach((packageJsonFile) => {
+        // Unfortunately jest custom message do not exist in loops,
+        // so using an exception instead to show failing package file
         // (see https://github.com/facebook/jest/issues/3293)
-        // expect(packageJsonFile.content.publishConfig?.access).toEqual('public');
+        // expect(packageJsonFile.content.publishConfig?.access)
+        //  .toEqual('public');
         if (packageJsonFile.content.publishConfig?.access !== 'public') {
           throw new Error(
             `Package ${packageJsonFile.file} does not have publishConfig.access: 'public'`,
           );
         }
-      }
-    });
+      });
   });
 });

__tests__/validate-tsconfig.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'fs-extra';
+import {Globby} from '@docusaurus/utils';
+import {Joi} from '@docusaurus/utils-validation';
+
+type TsconfigFile = {
+  file: string;
+  content: {
+    extends?: string;
+    compilerOptions: {
+      [key: string]: unknown;
+    };
+  };
+};
+
+async function getTsconfigFiles(): Promise<TsconfigFile[]> {
+  const files = await Globby('packages/*/tsconfig.*');
+  return Promise.all(
+    files.map((file) =>
+      fs
+        .readJSON(file)
+        .then((content: TsconfigFile['content']) => ({file, content})),
+    ),
+  );
+}
+
+const tsconfigSchema = Joi.object({
+  extends: Joi.valid(
+    '../../tsconfig.base.json',
+    '../../tsconfig.base.client.json',
+  ),
+}).unknown();
+
+describe('tsconfig files', () => {
+  it('contain all required fields', async () => {
+    const tsconfigFiles = await getTsconfigFiles();
+
+    tsconfigFiles
+      // Ignore noEmit configs
+      .forEach((file) => {
+        try {
+          Joi.attempt(file.content, tsconfigSchema);
+        } catch (e) {
+          (
+            e as Error
+          ).message += `\n${file.file} does not match the required schema.`;
+          throw e;
+        }
+      });
+  });
+});

admin/img/browserstack-dark-mode-logo.svg

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="180px" height="32px" viewBox="0 0 180 32" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g transform="translate(-40.000000, -16.000000)">
+            <g transform="translate(40.000000, 16.000000)">
+                <g>
+                    <g>
+                        <path d="M31.0344828,15.5172414 C31.0344828,24.0874296 24.0874296,31.0344828 15.5172414,31.0344828 C6.94734717,31.0344828 0,24.0874296 0,15.5172414 C0,6.94734717 6.94734717,0 15.5172414,0 C24.0874296,0 31.0344828,6.94734717 31.0344828,15.5172414" id="Fill-1" fill="#ECB360"></path>
+                        <path d="M26.8965517,13.9655172 C26.8965517,21.6784019 20.8752148,27.9310345 13.4482759,27.9310345 C6.02105363,27.9310345 0,21.6784019 0,13.9655172 C0,6.25263261 6.02105363,0 13.4482759,0 C20.8752148,0 26.8965517,6.25263261 26.8965517,13.9655172" id="Fill-2" fill="#D76835"></path>
+                        <path d="M27.9310345,12.4136422 C27.9310345,19.2697074 22.6047339,24.8275862 16.034049,24.8275862 C9.4642316,24.8275862 4.13793103,19.2697074 4.13793103,12.4136422 C4.13793103,5.55787885 9.4642316,0 16.034049,0 C22.6047339,0 27.9310345,5.55787885 27.9310345,12.4136422" id="Fill-3" fill="#D33A41"></path>
+                        <path d="M26.8965517,13.4484262 C26.8965517,19.7327316 22.0332814,24.8275862 16.0343393,24.8275862 C10.0353971,24.8275862 5.17241379,19.7327316 5.17241379,13.4484262 C5.17241379,7.16351943 10.0353971,2.06896552 16.0343393,2.06896552 C22.0332814,2.06896552 26.8965517,7.16351943 26.8965517,13.4484262" id="Fill-4" fill="#B6CB46"></path>
+                        <path d="M25.862069,14.4826111 C25.862069,20.1959217 21.2304045,24.8275862 15.5170939,24.8275862 C9.80407825,24.8275862 5.17241379,20.1959217 5.17241379,14.4826111 C5.17241379,8.76930045 9.80407825,4.13793103 15.5170939,4.13793103 C21.2304045,4.13793103 25.862069,8.76930045 25.862069,14.4826111" id="Fill-5" fill="#66AD4A"></path>
+                        <path d="M21.7241379,12.4137931 C21.7241379,16.9844178 18.0189006,20.6896552 13.4482759,20.6896552 C8.87737075,20.6896552 5.17241379,16.9844178 5.17241379,12.4137931 C5.17241379,7.84316841 8.87737075,4.13793103 13.4482759,4.13793103 C18.0189006,4.13793103 21.7241379,7.84316841 21.7241379,12.4137931" id="Fill-6" fill="#AED7DC"></path>
+                        <path d="M22.7586207,11.3793103 C22.7586207,15.3784867 19.5166452,18.6206897 15.5170948,18.6206897 C11.5175443,18.6206897 8.27586207,15.3784867 8.27586207,11.3793103 C8.27586207,7.37984085 11.5175443,4.13793103 15.5170948,4.13793103 C19.5166452,4.13793103 22.7586207,7.37984085 22.7586207,11.3793103" id="Fill-7" fill="#5BB1CF"></path>
+                        <path d="M22.7586207,11.8963967 C22.7586207,15.6100389 19.9797805,18.6206897 16.5517241,18.6206897 C13.1236677,18.6206897 10.3448276,15.6100389 10.3448276,11.8963967 C10.3448276,8.18306453 13.1236677,5.17241379 16.5517241,5.17241379 C19.9797805,5.17241379 22.7586207,8.18306453 22.7586207,11.8963967" id="Fill-8" fill="#25A8C3"></path>
+                        <path d="M20.6896552,12.9308813 C20.6896552,16.0732337 18.3737862,18.6206897 15.5171021,18.6206897 C12.6606966,18.6206897 10.3448276,16.0732337 10.3448276,12.9308813 C10.3448276,9.78852889 12.6606966,7.24137931 15.5171021,7.24137931 C18.3737862,7.24137931 20.6896552,9.78852889 20.6896552,12.9308813" id="Fill-9"></path>
+                        <path d="M15.5171021,18.6206897 C12.6606966,18.6206897 10.3448276,16.0732337 10.3448276,12.9308813 C10.3448276,9.78852889 12.6606966,7.24137931 15.5171021,7.24137931 C18.3737862,7.24137931 20.6896552,9.78852889 20.6896552,12.9308813 C20.6896552,16.0732337 18.3737862,18.6206897 15.5171021,18.6206897 Z" id="Fill-11" fill="#1B1A18"></path>
+                        <path d="M18.3395432,11.2904163 C17.8474621,12.1136138 16.8799806,12.5897073 16.1782532,12.3530843 C15.4765258,12.116746 15.3066858,11.2573859 15.7983878,10.4339036 C16.2904689,9.61042129 17.2579504,9.13461253 17.9596778,9.37095081 C18.6614052,9.60728909 18.8312452,10.4666492 18.3395432,11.2904163" id="Fill-12" fill="#FFFFFE"></path>
+                    </g>
+                    <g transform="translate(40.344828, 7.241379)" fill="#FFFFFF">
+                        <path d="M117.326492,14.0927618 C117.079145,13.39893 116.955659,12.5196449 116.955659,11.3399025 C116.955659,10.16016 117.079145,9.28125569 117.326492,8.58704314 C118.018463,6.59770338 119.848911,5.51049721 122.247091,5.51049721 C124.027467,5.51049721 125.43701,6.18109969 126.376328,7.24545739 C126.450871,7.33799367 126.475343,7.47698851 126.351857,7.56952479 L124.793981,8.84142273 C124.670496,8.93395901 124.546634,8.91111055 124.447996,8.79534499 C123.854663,8.17082025 123.236482,7.82390438 122.247091,7.82390438 C121.183911,7.82390438 120.367701,8.30981509 120.021339,9.28125569 C119.823687,9.83647341 119.774368,10.4842274 119.774368,11.3399025 C119.774368,12.1959583 119.823687,12.8669416 120.021339,13.4221593 C120.367701,14.3703706 121.183911,14.8562814 122.247091,14.8562814 C123.236482,14.8562814 123.854663,14.5093655 124.447996,13.8848407 C124.546634,13.7690752 124.670496,13.7690752 124.793981,13.8616115 L126.351857,15.1338902 C126.475343,15.2264265 126.450871,15.3421921 126.376328,15.4575768 C125.43701,16.4987052 124.027467,17.1696885 122.247091,17.1696885 C119.848911,17.1696885 118.018463,16.0824824 117.326492,14.0927618" id="Fill-23"></path>
+                        <path d="M136.031168,16.9153089 C135.858364,16.9153089 135.734502,16.8460019 135.635487,16.6837778 L132.61875,12.0108857 L131.011555,13.7458459 L131.011555,16.6837778 C131.011555,16.8227726 130.912917,16.9153089 130.764584,16.9153089 L128.489136,16.9153089 C128.341179,16.9153089 128.242165,16.8227726 128.242165,16.6837778 L128.242165,1.41567133 C128.242165,1.2770573 128.341179,1.18452102 128.489136,1.18452102 L130.764584,1.18452102 C130.912917,1.18452102 131.011555,1.2770573 131.011555,1.41567133 L131.011555,10.4842274 L135.09185,5.99640792 C135.239806,5.83418381 135.363668,5.7648768 135.561321,5.7648768 L138.083739,5.7648768 C138.232073,5.7648768 138.281392,5.90349083 138.182377,5.99640792 L134.399126,10.0676237 L138.751239,16.6837778 C138.825782,16.7763141 138.776087,16.9153089 138.627754,16.9153089 L136.031168,16.9153089" id="Fill-25"></path>
+                        <path d="M3.44757063,14.5093655 L6.95900335,14.5093655 C8.5910459,14.5093655 9.50589328,13.6300804 9.50589328,12.3117239 C9.50589328,11.0162159 8.5910459,10.1373115 6.95900335,10.1373115 L3.44757063,10.1373115 C3.34893277,10.1373115 3.29923736,10.1833893 3.29923736,10.2759256 L3.29923736,14.3703706 C3.29923736,14.4629069 3.34893277,14.5093655 3.44757063,14.5093655 Z M6.81067007,7.73136809 C8.29437934,7.73136809 9.20922672,6.89854151 9.20922672,5.67234051 C9.20922672,4.42329105 8.29437934,3.59046447 6.81067007,3.59046447 L3.44757063,3.59046447 C3.34893277,3.59046447 3.29923736,3.63654221 3.29923736,3.7290785 L3.29923736,7.59237326 C3.29923736,7.68490955 3.34893277,7.73136809 3.44757063,7.73136809 L6.81067007,7.73136809 Z M0.381514233,1.41567133 C0.381514233,1.2770573 0.480528579,1.18452102 0.628485378,1.18452102 L6.88483671,1.18452102 C10.4455884,1.18452102 12.1269498,2.85017418 12.1269498,5.37150238 C12.1269498,7.1529211 11.2369502,8.17082025 10.173393,8.7028087 L10.173393,8.74926725 C11.2121025,9.11903159 12.4236164,10.3684619 12.4236164,12.2884946 C12.4236164,15.4114991 10.3217263,16.9153089 6.63748909,16.9153089 L0.628485378,16.9153089 C0.480528579,16.9153089 0.381514233,16.8227726 0.381514233,16.6837778 L0.381514233,1.41567133 Z" id="Fill-13"></path>
+                        <path d="M14.4750581,16.9153089 C14.3263484,16.9153089 14.227334,16.8227726 14.227334,16.6837778 L14.227334,5.99640792 C14.227334,5.85741309 14.3263484,5.7648768 14.4750581,5.7648768 L16.7497527,5.7648768 C16.898086,5.7648768 16.9971003,5.85741309 16.9971003,5.99640792 L16.9971003,6.94461925 L17.021948,6.94461925 C17.5904334,6.08894421 18.6042952,5.51049721 20.1128521,5.51049721 C21.0521708,5.51049721 21.9918658,5.85741309 22.6100467,6.43586008 C22.7339087,6.55124483 22.7587564,6.64416193 22.6593656,6.75954668 L21.3488373,8.30981509 C21.2501994,8.42519984 21.1263374,8.44842911 21.0028518,8.35589283 C20.4588376,8.03182542 19.8899758,7.82390438 19.2473237,7.82390438 C17.6894478,7.82390438 16.9971003,8.864652 16.9971003,10.6460707 L16.9971003,16.6837778 C16.9971003,16.8227726 16.898086,16.9153089 16.7497527,16.9153089 L14.4750581,16.9153089" id="Fill-14"></path>
+                        <path d="M30.2623873,13.39893 C30.460416,12.820483 30.509735,12.2884946 30.509735,11.3399025 C30.509735,10.3916911 30.460416,9.88255115 30.2623873,9.28125569 C29.9160254,8.35589283 29.1498877,7.82390438 28.0370117,7.82390438 C26.9241356,7.82390438 26.1327738,8.35589283 25.7867883,9.28125569 C25.5891361,9.88255115 25.5394407,10.3916911 25.5394407,11.3399025 C25.5394407,12.2884946 25.5891361,12.820483 25.7867883,13.39893 C26.1327738,14.3242929 26.9241356,14.8562814 28.0370117,14.8562814 C29.1498877,14.8562814 29.9160254,14.3242929 30.2623873,13.39893 Z M23.1164128,14.0927618 C22.8442175,13.3063938 22.7207319,12.5661035 22.7207319,11.3399025 C22.7207319,10.1140823 22.8442175,9.37379198 23.1164128,8.58704314 C23.7839126,6.64416193 25.6136073,5.51049721 28.0370117,5.51049721 C30.4355683,5.51049721 32.2652631,6.64416193 32.9331393,8.58704314 C33.2049582,9.37379198 33.3288202,10.1140823 33.3288202,11.3399025 C33.3288202,12.5661035 33.2049582,13.3063938 32.9331393,14.0927618 C32.2652631,16.0360238 30.4355683,17.1696885 28.0370117,17.1696885 C25.6136073,17.1696885 23.7839126,16.0360238 23.1164128,14.0927618 Z" id="Fill-15"></path>
+                        <path d="M45.3234858,16.9153089 C45.1747761,16.9153089 45.0761382,16.8227726 45.0264428,16.6837778 L42.7269005,9.55886455 L42.6775816,9.55886455 L40.3531916,16.6837778 C40.3034962,16.8227726 40.2048583,16.9153089 40.0561485,16.9153089 L38.0288016,16.9153089 C37.8800918,16.9153089 37.7814539,16.8227726 37.732135,16.6837778 L33.9733547,5.99640792 C33.9236592,5.85741309 33.9982024,5.7648768 34.1465356,5.7648768 L36.5202446,5.7648768 C36.6934256,5.7648768 36.7924399,5.83418381 36.8417589,5.99640792 L39.1413012,13.3528523 L39.1909966,13.3528523 L41.4656912,5.99640792 C41.5153866,5.85741309 41.6388721,5.7648768 41.7872054,5.7648768 L43.5675812,5.7648768 C43.7159145,5.7648768 43.8397766,5.85741309 43.8890955,5.99640792 L46.3124999,13.3528523 L46.3618188,13.3528523 L48.5378755,5.99640792 C48.5871945,5.83418381 48.6862088,5.7648768 48.8593898,5.7648768 L51.2330987,5.7648768 C51.381432,5.7648768 51.4555987,5.85741309 51.4062797,5.99640792 L47.6474994,16.6837778 C47.5981804,16.8227726 47.4991661,16.9153089 47.3508328,16.9153089 L45.3234858,16.9153089" id="Fill-16"></path>
+                        <path d="M51.8938218,15.4114991 C51.795184,15.3189628 51.795184,15.1803488 51.8938218,15.0878125 L53.3033645,13.6997682 C53.4023788,13.6072319 53.5507121,13.6072319 53.6497264,13.6997682 C54.5152549,14.4400585 55.8999498,14.9720469 57.1363115,14.9720469 C58.595173,14.9720469 59.3368394,14.4168292 59.3368394,13.6533096 C59.3368394,12.9823263 58.9166873,12.5661035 57.3588114,12.4271086 L56.0727543,12.3117239 C53.6497264,12.0801928 52.4129883,10.9236796 52.4129883,9.0264953 C52.4129883,6.87531224 54.0698786,5.51049721 57.0372971,5.51049721 C58.8918396,5.51049721 60.4497155,6.08894421 61.5128961,6.87531224 C61.6367582,6.96784853 61.6367582,7.10646255 61.5625915,7.19899884 L60.3507011,8.56419467 C60.2520633,8.67957943 60.1282012,8.67957943 60.0047156,8.61027241 C59.2626728,8.12436171 58.0760065,7.68490955 56.8889638,7.68490955 C55.7019211,7.68490955 55.0837403,8.17082025 55.0837403,8.84142273 C55.0837403,9.48955754 55.5042689,9.88255115 57.0372971,10.021546 L58.3229777,10.1373115 C60.8205487,10.3684619 62.0075914,11.5714336 62.0075914,13.39893 C62.0075914,15.6198009 60.2765345,17.1696885 57.0124494,17.1696885 C54.5645738,17.1696885 52.8832123,16.2675549 51.8938218,15.4114991" id="Fill-17"></path>
+                        <path d="M71.0995931,9.14226086 C70.7780788,8.24012727 69.8877027,7.70813882 68.7752031,7.70813882 C67.6378558,7.70813882 66.7474797,8.24012727 66.4263419,9.14226086 C66.326951,9.41986972 66.2776321,9.69747858 66.2776321,10.090853 C66.2776321,10.1833893 66.326951,10.2298478 66.4263419,10.2298478 L71.0995931,10.2298478 C71.1986075,10.2298478 71.2479264,10.1833893 71.2479264,10.090853 C71.2479264,9.69747858 71.1986075,9.41986972 71.0995931,9.14226086 Z M63.9039232,14.0695325 C63.6565755,13.3528523 63.4833946,12.4967965 63.4833946,11.3399025 C63.4833946,10.1833893 63.6321043,9.30448497 63.8790755,8.58704314 C64.5465752,6.64416193 66.37627,5.51049721 68.7503554,5.51049721 C71.1986075,5.51049721 72.9789833,6.69023967 73.646483,8.58704314 C73.9186784,9.37379198 74.0421639,10.1373115 74.0421639,11.9415787 C74.0421639,12.0801928 73.9431496,12.172729 73.7703451,12.172729 L66.4263419,12.172729 C66.326951,12.172729 66.2776321,12.2191876 66.2776321,12.3117239 C66.2776321,12.6354105 66.3517988,12.9130193 66.4508131,13.1673989 C66.846494,14.2549859 67.7861891,14.8562814 69.1211886,14.8562814 C70.4565646,14.8562814 71.3224695,14.3935999 71.9154261,13.7923045 C72.0392882,13.6765389 72.1627738,13.6533096 72.2862593,13.7458459 L73.7454974,14.9488176 C73.868983,15.0413539 73.868983,15.1571195 73.7703451,15.272885 C72.7564834,16.3829397 71.0747454,17.1696885 68.8742175,17.1696885 C66.3517988,17.1696885 64.5714229,16.0131753 63.9039232,14.0695325 Z" id="Fill-18"></path>
+                        <path d="M76.0928527,16.9153089 C75.9448959,16.9153089 75.8458816,16.8227726 75.8458816,16.6837778 L75.8458816,5.99640792 C75.8458816,5.85741309 75.9448959,5.7648768 76.0928527,5.7648768 L78.3679238,5.7648768 C78.5166335,5.7648768 78.6152714,5.85741309 78.6152714,5.99640792 L78.6152714,6.94461925 L78.6401191,6.94461925 C79.2086045,6.08894421 80.2224662,5.51049721 81.7310232,5.51049721 C82.6707183,5.51049721 83.6100369,5.85741309 84.2282177,6.43586008 C84.3520798,6.55124483 84.376551,6.64416193 84.2779131,6.75954668 L82.9673849,8.30981509 C82.868747,8.42519984 82.7448849,8.44842911 82.6210229,8.35589283 C82.0773852,8.03182542 81.5085233,7.82390438 80.8658712,7.82390438 C79.3079953,7.82390438 78.6152714,8.864652 78.6152714,10.6460707 L78.6152714,16.6837778 C78.6152714,16.8227726 78.5166335,16.9153089 78.3679238,16.9153089 L76.0928527,16.9153089" id="Fill-19"></path>
+                        <path d="M84.704089,15.0878125 C84.6050746,14.9952762 84.5557557,14.8562814 84.65477,14.7405158 L86.1877982,13.0748626 C86.2868126,12.9594779 86.4351458,12.9594779 86.5337837,13.0520142 C87.6221886,13.8616115 89.2293834,14.7172865 91.1083971,14.7172865 C93.1112728,14.7172865 94.2734678,13.7690752 94.2734678,12.4507187 C94.2734678,11.317054 93.5318014,10.5767637 91.2074114,10.2759256 L90.3170353,10.16016 C87.0781744,9.74393713 85.2481031,8.28620501 85.2481031,5.67234051 C85.2481031,2.8269449 87.4734788,0.930141431 90.9352161,0.930141431 C93.0371062,0.930141431 95.0399819,1.55466616 96.3753579,2.5028775 C96.49922,2.59579459 96.5240677,2.68833088 96.4250533,2.8269449 L95.2380106,4.5386758 C95.1393728,4.65444136 95.0155107,4.67767064 94.8916487,4.60836362 C93.5318014,3.77553704 92.2705921,3.38216262 90.8614259,3.38216262 C89.1548403,3.38216262 88.2155217,4.26144775 88.2155217,5.48726794 C88.2155217,6.57447411 89.0313547,7.3147644 91.3064258,7.61560253 L92.1968019,7.73136809 C95.4356628,8.14759098 97.2160387,9.58171302 97.2160387,12.2884946 C97.2160387,15.0878125 95.0648296,17.1696885 90.8858972,17.1696885 C88.4135504,17.1696885 86.0146172,16.2443257 84.704089,15.0878125" id="Fill-20"></path>
+                        <path d="M102.339937,17.1118057 C99.9413803,17.1118057 99.0265329,16.0245996 99.0265329,13.8498064 L99.0265329,7.97432345 C99.0265329,7.88178716 98.9768375,7.83532861 98.8778232,7.83532861 L98.0864614,7.83532861 C97.9385046,7.83532861 97.8394902,7.74279233 97.8394902,7.60379749 L97.8394902,6.05390989 C97.8394902,5.91529587 97.9385046,5.82275958 98.0864614,5.82275958 L98.8778232,5.82275958 C98.9768375,5.82275958 99.0265329,5.77630103 99.0265329,5.68376475 L99.0265329,2.63006729 C99.0265329,2.49145326 99.1255473,2.39891698 99.2735041,2.39891698 L101.548575,2.39891698 C101.696908,2.39891698 101.795923,2.49145326 101.795923,2.63006729 L101.795923,5.68376475 C101.795923,5.77630103 101.845242,5.82275958 101.944256,5.82275958 L103.52698,5.82275958 C103.674936,5.82275958 103.773951,5.91529587 103.773951,6.05390989 L103.773951,7.60379749 C103.773951,7.74279233 103.674936,7.83532861 103.52698,7.83532861 L101.944256,7.83532861 C101.845242,7.83532861 101.795923,7.88178716 101.795923,7.97432345 L101.795923,13.757651 C101.795923,14.544019 102.142285,14.7983986 102.908799,14.7983986 L103.52698,14.7983986 C103.674936,14.7983986 103.773951,14.8909349 103.773951,15.0299297 L103.773951,16.8802746 C103.773951,17.0192695 103.674936,17.1118057 103.52698,17.1118057 L102.339937,17.1118057" id="Fill-21"></path>
+                        <path d="M112.530885,13.1673989 L112.530885,12.3117239 C112.530885,12.2191876 112.48119,12.172729 112.382175,12.172729 L110.404147,12.172729 C108.623771,12.172729 107.83241,12.6354105 107.83241,13.6765389 C107.83241,14.6019018 108.549228,15.0645832 109.884604,15.0645832 C111.59119,15.0645832 112.530885,14.4400585 112.530885,13.1673989 Z M112.827175,16.9153089 C112.678842,16.9153089 112.580204,16.8227726 112.580204,16.6837778 L112.580204,15.8741805 L112.555356,15.8741805 C111.986494,16.6377001 110.873618,17.1696885 109.192633,17.1696885 C107.016577,17.1696885 105.186505,16.1057116 105.186505,13.7690752 C105.186505,11.3399025 107.016577,10.2298478 109.958771,10.2298478 L112.382175,10.2298478 C112.48119,10.2298478 112.530885,10.1833893 112.530885,10.090853 L112.530885,9.55886455 C112.530885,8.28620501 111.88748,7.70813882 109.884604,7.70813882 C108.549228,7.70813882 107.733395,8.05505469 107.164533,8.47165839 C107.041048,8.56419467 106.892714,8.5409654 106.818548,8.42519984 L105.9037,6.89854151 C105.829534,6.78277595 105.854382,6.66701039 105.953019,6.59770338 C106.917562,5.94994937 108.22809,5.51049721 110.181647,5.51049721 C113.816566,5.51049721 115.151942,6.66701039 115.151942,9.39702125 L115.151942,16.6837778 C115.151942,16.8227726 115.052551,16.9153089 114.904594,16.9153089 L112.827175,16.9153089 Z" id="Fill-22"></path>
+                    </g>
+                </g>
+            </g>
+        </g>
+    </g>
+</svg>

admin/img/browserstack-light-mode-logo.svg

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="180px" height="32px" viewBox="0 0 180 32" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g transform="translate(-40.000000, -16.000000)">
+            <g transform="translate(40.000000, 16.000000)">
+                <g>
+                    <g>
+                        <path d="M31.0344828,15.5172414 C31.0344828,24.0874296 24.0874296,31.0344828 15.5172414,31.0344828 C6.94734717,31.0344828 0,24.0874296 0,15.5172414 C0,6.94734717 6.94734717,0 15.5172414,0 C24.0874296,0 31.0344828,6.94734717 31.0344828,15.5172414" id="Fill-1" fill="#ECB360"></path>
+                        <path d="M26.8965517,13.9655172 C26.8965517,21.6784019 20.8752148,27.9310345 13.4482759,27.9310345 C6.02105363,27.9310345 0,21.6784019 0,13.9655172 C0,6.25263261 6.02105363,0 13.4482759,0 C20.8752148,0 26.8965517,6.25263261 26.8965517,13.9655172" id="Fill-2" fill="#D76835"></path>
+                        <path d="M27.9310345,12.4136422 C27.9310345,19.2697074 22.6047339,24.8275862 16.034049,24.8275862 C9.4642316,24.8275862 4.13793103,19.2697074 4.13793103,12.4136422 C4.13793103,5.55787885 9.4642316,0 16.034049,0 C22.6047339,0 27.9310345,5.55787885 27.9310345,12.4136422" id="Fill-3" fill="#D33A41"></path>
+                        <path d="M26.8965517,13.4484262 C26.8965517,19.7327316 22.0332814,24.8275862 16.0343393,24.8275862 C10.0353971,24.8275862 5.17241379,19.7327316 5.17241379,13.4484262 C5.17241379,7.16351943 10.0353971,2.06896552 16.0343393,2.06896552 C22.0332814,2.06896552 26.8965517,7.16351943 26.8965517,13.4484262" id="Fill-4" fill="#B6CB46"></path>
+                        <path d="M25.862069,14.4826111 C25.862069,20.1959217 21.2304045,24.8275862 15.5170939,24.8275862 C9.80407825,24.8275862 5.17241379,20.1959217 5.17241379,14.4826111 C5.17241379,8.76930045 9.80407825,4.13793103 15.5170939,4.13793103 C21.2304045,4.13793103 25.862069,8.76930045 25.862069,14.4826111" id="Fill-5" fill="#66AD4A"></path>
+                        <path d="M21.7241379,12.4137931 C21.7241379,16.9844178 18.0189006,20.6896552 13.4482759,20.6896552 C8.87737075,20.6896552 5.17241379,16.9844178 5.17241379,12.4137931 C5.17241379,7.84316841 8.87737075,4.13793103 13.4482759,4.13793103 C18.0189006,4.13793103 21.7241379,7.84316841 21.7241379,12.4137931" id="Fill-6" fill="#AED7DC"></path>
+                        <path d="M22.7586207,11.3793103 C22.7586207,15.3784867 19.5166452,18.6206897 15.5170948,18.6206897 C11.5175443,18.6206897 8.27586207,15.3784867 8.27586207,11.3793103 C8.27586207,7.37984085 11.5175443,4.13793103 15.5170948,4.13793103 C19.5166452,4.13793103 22.7586207,7.37984085 22.7586207,11.3793103" id="Fill-7" fill="#5BB1CF"></path>
+                        <path d="M22.7586207,11.8963967 C22.7586207,15.6100389 19.9797805,18.6206897 16.5517241,18.6206897 C13.1236677,18.6206897 10.3448276,15.6100389 10.3448276,11.8963967 C10.3448276,8.18306453 13.1236677,5.17241379 16.5517241,5.17241379 C19.9797805,5.17241379 22.7586207,8.18306453 22.7586207,11.8963967" id="Fill-8" fill="#25A8C3"></path>
+                        <path d="M20.6896552,12.9308813 C20.6896552,16.0732337 18.3737862,18.6206897 15.5171021,18.6206897 C12.6606966,18.6206897 10.3448276,16.0732337 10.3448276,12.9308813 C10.3448276,9.78852889 12.6606966,7.24137931 15.5171021,7.24137931 C18.3737862,7.24137931 20.6896552,9.78852889 20.6896552,12.9308813" id="Fill-9"></path>
+                        <path d="M15.5171021,18.6206897 C12.6606966,18.6206897 10.3448276,16.0732337 10.3448276,12.9308813 C10.3448276,9.78852889 12.6606966,7.24137931 15.5171021,7.24137931 C18.3737862,7.24137931 20.6896552,9.78852889 20.6896552,12.9308813 C20.6896552,16.0732337 18.3737862,18.6206897 15.5171021,18.6206897 Z" id="Fill-11" fill="#1B1A18"></path>
+                        <path d="M18.3395432,11.2904163 C17.8474621,12.1136138 16.8799806,12.5897073 16.1782532,12.3530843 C15.4765258,12.116746 15.3066858,11.2573859 15.7983878,10.4339036 C16.2904689,9.61042129 17.2579504,9.13461253 17.9596778,9.37095081 C18.6614052,9.60728909 18.8312452,10.4666492 18.3395432,11.2904163" id="Fill-12" fill="#FFFFFE"></path>
+                    </g>
+                    <g transform="translate(40.344828, 7.241379)" fill="#202020">
+                        <path d="M117.326492,14.0927618 C117.079145,13.39893 116.955659,12.5196449 116.955659,11.3399025 C116.955659,10.16016 117.079145,9.28125569 117.326492,8.58704314 C118.018463,6.59770338 119.848911,5.51049721 122.247091,5.51049721 C124.027467,5.51049721 125.43701,6.18109969 126.376328,7.24545739 C126.450871,7.33799367 126.475343,7.47698851 126.351857,7.56952479 L124.793981,8.84142273 C124.670496,8.93395901 124.546634,8.91111055 124.447996,8.79534499 C123.854663,8.17082025 123.236482,7.82390438 122.247091,7.82390438 C121.183911,7.82390438 120.367701,8.30981509 120.021339,9.28125569 C119.823687,9.83647341 119.774368,10.4842274 119.774368,11.3399025 C119.774368,12.1959583 119.823687,12.8669416 120.021339,13.4221593 C120.367701,14.3703706 121.183911,14.8562814 122.247091,14.8562814 C123.236482,14.8562814 123.854663,14.5093655 124.447996,13.8848407 C124.546634,13.7690752 124.670496,13.7690752 124.793981,13.8616115 L126.351857,15.1338902 C126.475343,15.2264265 126.450871,15.3421921 126.376328,15.4575768 C125.43701,16.4987052 124.027467,17.1696885 122.247091,17.1696885 C119.848911,17.1696885 118.018463,16.0824824 117.326492,14.0927618" id="Fill-23"></path>
+                        <path d="M136.031168,16.9153089 C135.858364,16.9153089 135.734502,16.8460019 135.635487,16.6837778 L132.61875,12.0108857 L131.011555,13.7458459 L131.011555,16.6837778 C131.011555,16.8227726 130.912917,16.9153089 130.764584,16.9153089 L128.489136,16.9153089 C128.341179,16.9153089 128.242165,16.8227726 128.242165,16.6837778 L128.242165,1.41567133 C128.242165,1.2770573 128.341179,1.18452102 128.489136,1.18452102 L130.764584,1.18452102 C130.912917,1.18452102 131.011555,1.2770573 131.011555,1.41567133 L131.011555,10.4842274 L135.09185,5.99640792 C135.239806,5.83418381 135.363668,5.7648768 135.561321,5.7648768 L138.083739,5.7648768 C138.232073,5.7648768 138.281392,5.90349083 138.182377,5.99640792 L134.399126,10.0676237 L138.751239,16.6837778 C138.825782,16.7763141 138.776087,16.9153089 138.627754,16.9153089 L136.031168,16.9153089" id="Fill-25"></path>
+                        <path d="M3.44757063,14.5093655 L6.95900335,14.5093655 C8.5910459,14.5093655 9.50589328,13.6300804 9.50589328,12.3117239 C9.50589328,11.0162159 8.5910459,10.1373115 6.95900335,10.1373115 L3.44757063,10.1373115 C3.34893277,10.1373115 3.29923736,10.1833893 3.29923736,10.2759256 L3.29923736,14.3703706 C3.29923736,14.4629069 3.34893277,14.5093655 3.44757063,14.5093655 Z M6.81067007,7.73136809 C8.29437934,7.73136809 9.20922672,6.89854151 9.20922672,5.67234051 C9.20922672,4.42329105 8.29437934,3.59046447 6.81067007,3.59046447 L3.44757063,3.59046447 C3.34893277,3.59046447 3.29923736,3.63654221 3.29923736,3.7290785 L3.29923736,7.59237326 C3.29923736,7.68490955 3.34893277,7.73136809 3.44757063,7.73136809 L6.81067007,7.73136809 Z M0.381514233,1.41567133 C0.381514233,1.2770573 0.480528579,1.18452102 0.628485378,1.18452102 L6.88483671,1.18452102 C10.4455884,1.18452102 12.1269498,2.85017418 12.1269498,5.37150238 C12.1269498,7.1529211 11.2369502,8.17082025 10.173393,8.7028087 L10.173393,8.74926725 C11.2121025,9.11903159 12.4236164,10.3684619 12.4236164,12.2884946 C12.4236164,15.4114991 10.3217263,16.9153089 6.63748909,16.9153089 L0.628485378,16.9153089 C0.480528579,16.9153089 0.381514233,16.8227726 0.381514233,16.6837778 L0.381514233,1.41567133 Z" id="Fill-13"></path>
+                        <path d="M14.4750581,16.9153089 C14.3263484,16.9153089 14.227334,16.8227726 14.227334,16.6837778 L14.227334,5.99640792 C14.227334,5.85741309 14.3263484,5.7648768 14.4750581,5.7648768 L16.7497527,5.7648768 C16.898086,5.7648768 16.9971003,5.85741309 16.9971003,5.99640792 L16.9971003,6.94461925 L17.021948,6.94461925 C17.5904334,6.08894421 18.6042952,5.51049721 20.1128521,5.51049721 C21.0521708,5.51049721 21.9918658,5.85741309 22.6100467,6.43586008 C22.7339087,6.55124483 22.7587564,6.64416193 22.6593656,6.75954668 L21.3488373,8.30981509 C21.2501994,8.42519984 21.1263374,8.44842911 21.0028518,8.35589283 C20.4588376,8.03182542 19.8899758,7.82390438 19.2473237,7.82390438 C17.6894478,7.82390438 16.9971003,8.864652 16.9971003,10.6460707 L16.9971003,16.6837778 C16.9971003,16.8227726 16.898086,16.9153089 16.7497527,16.9153089 L14.4750581,16.9153089" id="Fill-14"></path>
+                        <path d="M30.2623873,13.39893 C30.460416,12.820483 30.509735,12.2884946 30.509735,11.3399025 C30.509735,10.3916911 30.460416,9.88255115 30.2623873,9.28125569 C29.9160254,8.35589283 29.1498877,7.82390438 28.0370117,7.82390438 C26.9241356,7.82390438 26.1327738,8.35589283 25.7867883,9.28125569 C25.5891361,9.88255115 25.5394407,10.3916911 25.5394407,11.3399025 C25.5394407,12.2884946 25.5891361,12.820483 25.7867883,13.39893 C26.1327738,14.3242929 26.9241356,14.8562814 28.0370117,14.8562814 C29.1498877,14.8562814 29.9160254,14.3242929 30.2623873,13.39893 Z M23.1164128,14.0927618 C22.8442175,13.3063938 22.7207319,12.5661035 22.7207319,11.3399025 C22.7207319,10.1140823 22.8442175,9.37379198 23.1164128,8.58704314 C23.7839126,6.64416193 25.6136073,5.51049721 28.0370117,5.51049721 C30.4355683,5.51049721 32.2652631,6.64416193 32.9331393,8.58704314 C33.2049582,9.37379198 33.3288202,10.1140823 33.3288202,11.3399025 C33.3288202,12.5661035 33.2049582,13.3063938 32.9331393,14.0927618 C32.2652631,16.0360238 30.4355683,17.1696885 28.0370117,17.1696885 C25.6136073,17.1696885 23.7839126,16.0360238 23.1164128,14.0927618 Z" id="Fill-15"></path>
+                        <path d="M45.3234858,16.9153089 C45.1747761,16.9153089 45.0761382,16.8227726 45.0264428,16.6837778 L42.7269005,9.55886455 L42.6775816,9.55886455 L40.3531916,16.6837778 C40.3034962,16.8227726 40.2048583,16.9153089 40.0561485,16.9153089 L38.0288016,16.9153089 C37.8800918,16.9153089 37.7814539,16.8227726 37.732135,16.6837778 L33.9733547,5.99640792 C33.9236592,5.85741309 33.9982024,5.7648768 34.1465356,5.7648768 L36.5202446,5.7648768 C36.6934256,5.7648768 36.7924399,5.83418381 36.8417589,5.99640792 L39.1413012,13.3528523 L39.1909966,13.3528523 L41.4656912,5.99640792 C41.5153866,5.85741309 41.6388721,5.7648768 41.7872054,5.7648768 L43.5675812,5.7648768 C43.7159145,5.7648768 43.8397766,5.85741309 43.8890955,5.99640792 L46.3124999,13.3528523 L46.3618188,13.3528523 L48.5378755,5.99640792 C48.5871945,5.83418381 48.6862088,5.7648768 48.8593898,5.7648768 L51.2330987,5.7648768 C51.381432,5.7648768 51.4555987,5.85741309 51.4062797,5.99640792 L47.6474994,16.6837778 C47.5981804,16.8227726 47.4991661,16.9153089 47.3508328,16.9153089 L45.3234858,16.9153089" id="Fill-16"></path>
+                        <path d="M51.8938218,15.4114991 C51.795184,15.3189628 51.795184,15.1803488 51.8938218,15.0878125 L53.3033645,13.6997682 C53.4023788,13.6072319 53.5507121,13.6072319 53.6497264,13.6997682 C54.5152549,14.4400585 55.8999498,14.9720469 57.1363115,14.9720469 C58.595173,14.9720469 59.3368394,14.4168292 59.3368394,13.6533096 C59.3368394,12.9823263 58.9166873,12.5661035 57.3588114,12.4271086 L56.0727543,12.3117239 C53.6497264,12.0801928 52.4129883,10.9236796 52.4129883,9.0264953 C52.4129883,6.87531224 54.0698786,5.51049721 57.0372971,5.51049721 C58.8918396,5.51049721 60.4497155,6.08894421 61.5128961,6.87531224 C61.6367582,6.96784853 61.6367582,7.10646255 61.5625915,7.19899884 L60.3507011,8.56419467 C60.2520633,8.67957943 60.1282012,8.67957943 60.0047156,8.61027241 C59.2626728,8.12436171 58.0760065,7.68490955 56.8889638,7.68490955 C55.7019211,7.68490955 55.0837403,8.17082025 55.0837403,8.84142273 C55.0837403,9.48955754 55.5042689,9.88255115 57.0372971,10.021546 L58.3229777,10.1373115 C60.8205487,10.3684619 62.0075914,11.5714336 62.0075914,13.39893 C62.0075914,15.6198009 60.2765345,17.1696885 57.0124494,17.1696885 C54.5645738,17.1696885 52.8832123,16.2675549 51.8938218,15.4114991" id="Fill-17"></path>
+                        <path d="M71.0995931,9.14226086 C70.7780788,8.24012727 69.8877027,7.70813882 68.7752031,7.70813882 C67.6378558,7.70813882 66.7474797,8.24012727 66.4263419,9.14226086 C66.326951,9.41986972 66.2776321,9.69747858 66.2776321,10.090853 C66.2776321,10.1833893 66.326951,10.2298478 66.4263419,10.2298478 L71.0995931,10.2298478 C71.1986075,10.2298478 71.2479264,10.1833893 71.2479264,10.090853 C71.2479264,9.69747858 71.1986075,9.41986972 71.0995931,9.14226086 Z M63.9039232,14.0695325 C63.6565755,13.3528523 63.4833946,12.4967965 63.4833946,11.3399025 C63.4833946,10.1833893 63.6321043,9.30448497 63.8790755,8.58704314 C64.5465752,6.64416193 66.37627,5.51049721 68.7503554,5.51049721 C71.1986075,5.51049721 72.9789833,6.69023967 73.646483,8.58704314 C73.9186784,9.37379198 74.0421639,10.1373115 74.0421639,11.9415787 C74.0421639,12.0801928 73.9431496,12.172729 73.7703451,12.172729 L66.4263419,12.172729 C66.326951,12.172729 66.2776321,12.2191876 66.2776321,12.3117239 C66.2776321,12.6354105 66.3517988,12.9130193 66.4508131,13.1673989 C66.846494,14.2549859 67.7861891,14.8562814 69.1211886,14.8562814 C70.4565646,14.8562814 71.3224695,14.3935999 71.9154261,13.7923045 C72.0392882,13.6765389 72.1627738,13.6533096 72.2862593,13.7458459 L73.7454974,14.9488176 C73.868983,15.0413539 73.868983,15.1571195 73.7703451,15.272885 C72.7564834,16.3829397 71.0747454,17.1696885 68.8742175,17.1696885 C66.3517988,17.1696885 64.5714229,16.0131753 63.9039232,14.0695325 Z" id="Fill-18"></path>
+                        <path d="M76.0928527,16.9153089 C75.9448959,16.9153089 75.8458816,16.8227726 75.8458816,16.6837778 L75.8458816,5.99640792 C75.8458816,5.85741309 75.9448959,5.7648768 76.0928527,5.7648768 L78.3679238,5.7648768 C78.5166335,5.7648768 78.6152714,5.85741309 78.6152714,5.99640792 L78.6152714,6.94461925 L78.6401191,6.94461925 C79.2086045,6.08894421 80.2224662,5.51049721 81.7310232,5.51049721 C82.6707183,5.51049721 83.6100369,5.85741309 84.2282177,6.43586008 C84.3520798,6.55124483 84.376551,6.64416193 84.2779131,6.75954668 L82.9673849,8.30981509 C82.868747,8.42519984 82.7448849,8.44842911 82.6210229,8.35589283 C82.0773852,8.03182542 81.5085233,7.82390438 80.8658712,7.82390438 C79.3079953,7.82390438 78.6152714,8.864652 78.6152714,10.6460707 L78.6152714,16.6837778 C78.6152714,16.8227726 78.5166335,16.9153089 78.3679238,16.9153089 L76.0928527,16.9153089" id="Fill-19"></path>
+                        <path d="M84.704089,15.0878125 C84.6050746,14.9952762 84.5557557,14.8562814 84.65477,14.7405158 L86.1877982,13.0748626 C86.2868126,12.9594779 86.4351458,12.9594779 86.5337837,13.0520142 C87.6221886,13.8616115 89.2293834,14.7172865 91.1083971,14.7172865 C93.1112728,14.7172865 94.2734678,13.7690752 94.2734678,12.4507187 C94.2734678,11.317054 93.5318014,10.5767637 91.2074114,10.2759256 L90.3170353,10.16016 C87.0781744,9.74393713 85.2481031,8.28620501 85.2481031,5.67234051 C85.2481031,2.8269449 87.4734788,0.930141431 90.9352161,0.930141431 C93.0371062,0.930141431 95.0399819,1.55466616 96.3753579,2.5028775 C96.49922,2.59579459 96.5240677,2.68833088 96.4250533,2.8269449 L95.2380106,4.5386758 C95.1393728,4.65444136 95.0155107,4.67767064 94.8916487,4.60836362 C93.5318014,3.77553704 92.2705921,3.38216262 90.8614259,3.38216262 C89.1548403,3.38216262 88.2155217,4.26144775 88.2155217,5.48726794 C88.2155217,6.57447411 89.0313547,7.3147644 91.3064258,7.61560253 L92.1968019,7.73136809 C95.4356628,8.14759098 97.2160387,9.58171302 97.2160387,12.2884946 C97.2160387,15.0878125 95.0648296,17.1696885 90.8858972,17.1696885 C88.4135504,17.1696885 86.0146172,16.2443257 84.704089,15.0878125" id="Fill-20"></path>
+                        <path d="M102.339937,17.1118057 C99.9413803,17.1118057 99.0265329,16.0245996 99.0265329,13.8498064 L99.0265329,7.97432345 C99.0265329,7.88178716 98.9768375,7.83532861 98.8778232,7.83532861 L98.0864614,7.83532861 C97.9385046,7.83532861 97.8394902,7.74279233 97.8394902,7.60379749 L97.8394902,6.05390989 C97.8394902,5.91529587 97.9385046,5.82275958 98.0864614,5.82275958 L98.8778232,5.82275958 C98.9768375,5.82275958 99.0265329,5.77630103 99.0265329,5.68376475 L99.0265329,2.63006729 C99.0265329,2.49145326 99.1255473,2.39891698 99.2735041,2.39891698 L101.548575,2.39891698 C101.696908,2.39891698 101.795923,2.49145326 101.795923,2.63006729 L101.795923,5.68376475 C101.795923,5.77630103 101.845242,5.82275958 101.944256,5.82275958 L103.52698,5.82275958 C103.674936,5.82275958 103.773951,5.91529587 103.773951,6.05390989 L103.773951,7.60379749 C103.773951,7.74279233 103.674936,7.83532861 103.52698,7.83532861 L101.944256,7.83532861 C101.845242,7.83532861 101.795923,7.88178716 101.795923,7.97432345 L101.795923,13.757651 C101.795923,14.544019 102.142285,14.7983986 102.908799,14.7983986 L103.52698,14.7983986 C103.674936,14.7983986 103.773951,14.8909349 103.773951,15.0299297 L103.773951,16.8802746 C103.773951,17.0192695 103.674936,17.1118057 103.52698,17.1118057 L102.339937,17.1118057" id="Fill-21"></path>
+                        <path d="M112.530885,13.1673989 L112.530885,12.3117239 C112.530885,12.2191876 112.48119,12.172729 112.382175,12.172729 L110.404147,12.172729 C108.623771,12.172729 107.83241,12.6354105 107.83241,13.6765389 C107.83241,14.6019018 108.549228,15.0645832 109.884604,15.0645832 C111.59119,15.0645832 112.530885,14.4400585 112.530885,13.1673989 Z M112.827175,16.9153089 C112.678842,16.9153089 112.580204,16.8227726 112.580204,16.6837778 L112.580204,15.8741805 L112.555356,15.8741805 C111.986494,16.6377001 110.873618,17.1696885 109.192633,17.1696885 C107.016577,17.1696885 105.186505,16.1057116 105.186505,13.7690752 C105.186505,11.3399025 107.016577,10.2298478 109.958771,10.2298478 L112.382175,10.2298478 C112.48119,10.2298478 112.530885,10.1833893 112.530885,10.090853 L112.530885,9.55886455 C112.530885,8.28620501 111.88748,7.70813882 109.884604,7.70813882 C108.549228,7.70813882 107.733395,8.05505469 107.164533,8.47165839 C107.041048,8.56419467 106.892714,8.5409654 106.818548,8.42519984 L105.9037,6.89854151 C105.829534,6.78277595 105.854382,6.66701039 105.953019,6.59770338 C106.917562,5.94994937 108.22809,5.51049721 110.181647,5.51049721 C113.816566,5.51049721 115.151942,6.66701039 115.151942,9.39702125 L115.151942,16.6837778 C115.151942,16.8227726 115.052551,16.9153089 114.904594,16.9153089 L112.827175,16.9153089 Z" id="Fill-22"></path>
+                    </g>
+                </g>
+            </g>
+        </g>
+    </g>
+</svg>

admin/new.docusaurus.io/README.md

@@ -2,7 +2,7 @@
 
 This is a Netlify deployment to handle the Docusaurus playgrounds shortcuts:
 
-- [docusaurus.new](https://docusaurus.new) (main one, as of today domain is owned by StackBlitz but may be transfered to FB)
+- [docusaurus.new](https://docusaurus.new) (main one, as of today domain is owned by StackBlitz but may be transferred to FB)
 - [new.docusaurus.io](https://new.docusaurus.io) (legacy one)
 
 See also the [Playground doc page](https://docusaurus.io/docs/playground)

admin/new.docusaurus.io/functionUtils/playgroundUtils.ts

@@ -5,16 +5,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {HandlerEvent, HandlerResponse} from '@netlify/functions';
+import type {HandlerEvent, HandlerResponse} from '@netlify/functions';
 
 const CookieName = 'DocusaurusPlaygroundName';
 
 const PlaygroundConfigs = {
-  codesandbox: 'https://codesandbox.io/s/docusaurus',
+  codesandbox:
+    'https://codesandbox.io/p/sandbox/github/facebook/docusaurus/tree/main/examples/classic?file=%2FREADME.md&privacy=public',
+  'codesandbox-ts':
+    'https://codesandbox.io/p/sandbox/github/facebook/docusaurus/tree/main/examples/classic-typescript?file=%2FREADME.md&privacy=public',
 
-  // stackblitz: 'https://stackblitz.com/fork/docusaurus', // not updated
-  // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic', // slow to load
-  stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/starter', // dedicated branch: faster load
+  // Slow to load
+  // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic',
+  // Dedicated branch: faster load
+  stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/starter',
+  'stackblitz-ts':
+    'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic-typescript',
 };
 
 const PlaygroundDocumentationUrl = 'https://docusaurus.io/docs/playground';
@@ -22,9 +28,11 @@ const PlaygroundDocumentationUrl = 'https://docusaurus.io/docs/playground';
 export type PlaygroundName = keyof typeof PlaygroundConfigs;
 
 function isValidPlaygroundName(
-  playgroundName: string,
+  playgroundName: string | undefined,
 ): playgroundName is PlaygroundName {
-  return Object.keys(PlaygroundConfigs).includes(playgroundName);
+  return (
+    !!playgroundName && Object.keys(PlaygroundConfigs).includes(playgroundName)
+  );
 }
 
 export function createPlaygroundDocumentationResponse(): HandlerResponse {
@@ -50,10 +58,10 @@ export function createPlaygroundResponse(
 }
 
 // Inspired by https://stackoverflow.com/a/3409200/82609
-function parseCookieString(cookieString: string): Record<string, string> {
-  const result: Record<string, string> = {};
+function parseCookieString(cookieString: string): {[key: string]: string} {
+  const result: {[key: string]: string} = {};
   cookieString.split(';').forEach((cookie) => {
-    const [name, value] = cookie.split('=');
+    const [name, value] = cookie.split('=') as [string, string];
     result[name.trim()] = decodeURI(value);
   });
   return result;
@@ -62,19 +70,16 @@ function parseCookieString(cookieString: string): Record<string, string> {
 export function readPlaygroundName(
   event: HandlerEvent,
 ): PlaygroundName | undefined {
-  const parsedCookie: Record<string, string> = event.headers.cookie
+  const parsedCookie: {[key: string]: string} = event.headers.cookie
     ? parseCookieString(event.headers.cookie)
     : {};
   const playgroundName: string | undefined = parsedCookie[CookieName];
 
-  if (playgroundName) {
-    if (isValidPlaygroundName(playgroundName)) {
-      return playgroundName;
-    } else {
-      console.error(
-        `playgroundName found in cookie was invalid: ${playgroundName}`,
-      );
-    }
+  if (!isValidPlaygroundName(playgroundName)) {
+    console.error(
+      `playgroundName found in cookie was invalid: ${playgroundName}`,
+    );
+    return undefined;
   }
-  return undefined;
+  return playgroundName;
 }

admin/new.docusaurus.io/functions/codesandbox-ts.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {createPlaygroundResponse} from '../functionUtils/playgroundUtils';
+import type {Handler} from '@netlify/functions';
+
+export const handler: Handler = () =>
+  Promise.resolve(createPlaygroundResponse('codesandbox-ts'));

admin/new.docusaurus.io/functions/codesandbox.ts

@@ -5,10 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Handler} from '@netlify/functions';
-
 import {createPlaygroundResponse} from '../functionUtils/playgroundUtils';
+import type {Handler} from '@netlify/functions';
 
-export const handler: Handler = async function (_event, _context) {
-  return createPlaygroundResponse('codesandbox');
-};
+export const handler: Handler = () =>
+  Promise.resolve(createPlaygroundResponse('codesandbox'));

admin/new.docusaurus.io/functions/index.ts

@@ -5,15 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Handler} from '@netlify/functions';
-
 import {
   readPlaygroundName,
   createPlaygroundResponse,
   createPlaygroundDocumentationResponse,
 } from '../functionUtils/playgroundUtils';
+import type {Handler} from '@netlify/functions';
 
-export const handler: Handler = async (event, _context) => {
+export const handler: Handler = async (event) => {
   const playgroundName = readPlaygroundName(event);
   return playgroundName
     ? createPlaygroundResponse(playgroundName)

admin/new.docusaurus.io/functions/stackblitz-ts.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {createPlaygroundResponse} from '../functionUtils/playgroundUtils';
+import type {Handler} from '@netlify/functions';
+
+export const handler: Handler = () =>
+  Promise.resolve(createPlaygroundResponse('stackblitz-ts'));

admin/new.docusaurus.io/functions/stackblitz.ts

@@ -5,10 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Handler} from '@netlify/functions';
-
 import {createPlaygroundResponse} from '../functionUtils/playgroundUtils';
+import type {Handler} from '@netlify/functions';
 
-export const handler: Handler = async function (_event, _context) {
-  return createPlaygroundResponse('stackblitz');
-};
+export const handler: Handler = () =>
+  Promise.resolve(createPlaygroundResponse('stackblitz'));

admin/new.docusaurus.io/netlify.toml

@@ -12,11 +12,21 @@ from    = "/codesandbox"
 to      = "/.netlify/functions/codesandbox"
 status  = 200
 
+[[redirects]]
+from    = "/codesandbox-ts"
+to      = "/.netlify/functions/codesandbox-ts"
+status  = 200
+
 [[redirects]]
 from    = "/stackblitz"
 to      = "/.netlify/functions/stackblitz"
 status  = 200
 
+[[redirects]]
+from    = "/stackblitz-ts"
+to      = "/.netlify/functions/stackblitz-ts"
+status  = 200
+
 [[redirects]]
 from    = "/*"
 to      = "/.netlify/functions/index"

admin/new.docusaurus.io/package.json

@@ -1,14 +1,11 @@
 {
   "name": "new.docusaurus.io",
-  "version": "2.0.0-beta.9",
+  "version": "3.9.2",
   "private": true,
   "scripts": {
-    "start": "netlify dev"
+    "start": "npx --package netlify-cli netlify dev"
   },
   "dependencies": {
-    "@netlify/functions": "^0.10.0"
-  },
-  "devDependencies": {
-    "netlify-cli": "^8.0.5"
+    "@netlify/functions": "^1.6.0"
   }
 }

admin/publish.md

@@ -10,7 +10,7 @@ Get access from the Docusaurus npm admins (@yangshun/@JoelMarcey).
 
 You need publish access to **the main Docusaurus repository** (not a fork).
 
-## NPM
+## npm
 
 Publishing will only work if you are logged into npm with an account with publishing rights to the package.
 
@@ -68,17 +68,28 @@ yarn serve
 
 This local test step is optional because it will be run by the CI on your release PR ([see](https://github.com/facebook/docusaurus/pull/2954/checks?check_run_id=780871959))
 
-### 3. Update the v2 changelog
+### 3. Update the changelog
 
-The changelog uses GitHub labels to classify each pull request. Use the GitHub interface to assign each newly merged pull request to a GitHub label starting with `tag:`, otherwise the PR won't appear in the changelog.
+The changelog uses GitHub labels to classify each pull request. Use the GitHub interface to assign each newly merged pull request to a GitHub label starting with `pr:`, otherwise the PR won't appear in the changelog.
 
-[Check tags of all recently merged Pull-Requests](https://github.com/facebook/docusaurus/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Amerged+)
+Not all labels will appear in the changelog—some are designed not to. However, you should **always** label each PR, so that before release, we can do a quick scan and confirm no PR is accidentally left out. Here's a search query (pity that GH doesn't have wildcard queries yet):
 
-The `tag:` label prefix is for PRs only. Other labels are not used by the changelog tool, and it's not necessary to assign such labels to issues, only PRs.
+```
+is:pr is:merged sort:updated-desc -label:"pr: breaking change","pr: new feature","pr: bug fix","pr: performance","pr: polish","pr: documentation","pr: maintenance","pr: internal","pr: dependencies","pr: showcase"
+```
+
+[Check tags of all recently merged Pull-Requests](https://github.com/facebook/docusaurus/pulls?q=is%3Apr+is%3Amerged+sort%3Aupdated-desc+-label%3A%22pr%3A+breaking+change%22%2C%22pr%3A+new+feature%22%2C%22pr%3A+bug+fix%22%2C%22pr%3A+performance%22%2C%22pr%3A+polish%22%2C%22pr%3A+documentation%22%2C%22pr%3A+maintenance%22%2C%22pr%3A+internal%22%2C%22pr%3A+dependencies%22%2C%22pr%3A+showcase%22%2C%22pr%3A+ignore%22%2C%22pr%3A+translations%22+)
+
+Some general principles about the labeling process:
+
+- "Will an average user be interested in this entry?" Items like "improve test coverage", "upgrade dependencies" can probably be left out (we have `pr: internal` and `pr: dependencies` for this). However, "pin GitHub actions to an SHA", "add visual testing infrastructure", etc., albeit internal, could be interesting to the user, and can be included in the "maintenance" section.
+- "Will this change have tangible impact on the user?" A common case is when a PR implements a feature X, then there are immediately follow-up PRs that fix bugs or polish feature X. These follow-up PRs don't necessarily have to be in the changelog, and even if they alter the API, they are not breaking changes, because to an average user bumping their version, they will only see the new feature X as a whole. Make the entries atomic.
+
+The `pr:` label prefix is for PRs only. Other labels are not used by the changelog tool, and it's not necessary to assign such labels to issues, only PRs.
 
 Generate a GitHub auth token by going to https://github.com/settings/tokens (the only permission needed is `public_repo`). Save the token somewhere for future reference.
 
-Fetch the tags from Github (lerna-changelog looks for commits since last tag by default):
+Fetch the tags from GitHub (lerna-changelog looks for commits since last tag by default):
 
 ```sh
 git fetch --tags
@@ -110,7 +121,7 @@ Test running the website with the new version locally.
 
 To keep versions number small, delete the oldest version and add a link to it in `archivedVersions.json`.
 
-Check [Netlify site deployments](https://app.netlify.com/sites/docusaurus-2/deploys) to pick a recent immutable deployment url.
+Check [Netlify site deployments](https://app.netlify.com/sites/docusaurus-2/deploys) to pick a recent immutable deployment URL.
 
 ### 5. Create a Pull Request
 
@@ -118,7 +129,7 @@ You should still be on your local branch `<your_username>/<version_to_release>`
 
 Make a commit/push, create a pull request with the changes.
 
-Example PR: [#3114](https://github.com/facebook/docusaurus/pull/5098), using title such as `chore(v2): prepare v2.0.0-beta.0 release`
+Example PR: [#3114](https://github.com/facebook/docusaurus/pull/5098), using title such as `chore: prepare v2.0.0-beta.0 release`
 
 **Don't merge it yet**, but wait for the CI checks to complete.
 
@@ -163,7 +174,7 @@ npm access ls-packages
 </pre>
 </details>
 
-It can happen that some accesses are not granted, as an admin might add you to the @docusaurus NPM organization, but you don't have access to the packages that are not in that organization.
+It can happen that some accesses are not granted, as an admin might add you to the @docusaurus npm organization, but you don't have access to the packages that are not in that organization.
 
 Please **double-check your permissions on these packages**, otherwise you'll publish a half-release and will have to release a new version.
 
@@ -176,7 +187,7 @@ If all accesses are available, build all the necessary packages, and then run th
 
 ```sh
 yarn build:packages
-yarn lerna publish --exact 2.0.0-beta.0
+yarn lerna publish  --force-publish --exact 2.0.0-beta.0
 ```
 
 This command does a few things:
@@ -187,6 +198,8 @@ This command does a few things:
 
 You should receive many emails notifying you that a new version of the packages has been published.
 
+If above command fail (network issue or whatever), you can try to recover with `yarn lerna publish from-package`: it will try to publish the packages that are missing on npm.
+
 Now that the release is done, **merge the pull request**.
 
 ### 7. Create a release on GitHub
@@ -205,7 +218,7 @@ Create a separate branch/PR and run `yarn examples:generate`
 
 ### 9. Notify people about new release (optional but desirable)
 
-After new release, it is cool to notify our users about this in the Discord chat (`#announcements` channel) and write summaries on Twitter using the following templates.
+After new release, it is cool to notify our users about this in the Discord chat (`#announcements` channel) and write summaries on X using the following templates.
 
 For Discord:
 
@@ -214,7 +227,7 @@ A new version %VER% is available now! 🎉
 See release notes at the following link https://github.com/facebook/docusaurus/releases/tag/%VER%
 ```
 
-For Twitter:
+For X:
 
 ```
 💥 A new version %VER% is available now! 💥

admin/scripts/copyUntypedFiles.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import chokidar from 'chokidar';
+
+const srcDir = path.join(process.cwd(), 'src');
+const libDir = path.join(process.cwd(), 'lib');
+
+const ignoredPattern = /(?:__tests__|\.tsx?$)/;
+
+async function copy() {
+  await fs.copy(srcDir, libDir, {
+    filter(testedPath) {
+      return !ignoredPattern.test(testedPath);
+    },
+  });
+}
+
+if (process.argv.includes('--watch')) {
+  const watcher = chokidar.watch(srcDir, {
+    ignored: ignoredPattern,
+    ignoreInitial: true,
+    persistent: true,
+  });
+  ['add', 'change', 'unlink', 'addDir', 'unlinkDir'].forEach((event) =>
+    watcher.on(event, copy),
+  );
+} else {
+  await copy();
+}

admin/scripts/formatLighthouseReport.js

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// @ts-check
+
+/** @typedef {Record<'performance' | 'accessibility' | 'best-practices' | 'seo', number>} LighthouseSummary */
+
+/** @type {Record<keyof LighthouseSummary, string>} */
+const summaryKeys = {
+  performance: 'Performance',
+  accessibility: 'Accessibility',
+  'best-practices': 'Best Practices',
+  seo: 'SEO',
+};
+
+/** @param {number} rawScore */
+const scoreEntry = (rawScore) => {
+  const score = Math.round(rawScore * 100);
+  // eslint-disable-next-line no-nested-ternary
+  const scoreIcon = score >= 90 ? '🟢' : score >= 50 ? '🟠' : '🔴';
+  return `${scoreIcon} ${score}`;
+};
+
+/**
+ * @param {string} url
+ * @returns {module:url.URL}
+ */
+function createURL(url) {
+  try {
+    return new URL(url);
+  } catch (e) {
+    throw new Error(`Can't create URL for string=${url}`, {cause: e});
+  }
+}
+
+/**
+ * @param {Object} param0
+ * @param {string} param0.url
+ * @param {LighthouseSummary} param0.summary
+ * @param {string | undefined} param0.reportUrl
+ * @return {string}
+ */
+const createMarkdownTableRow = ({url, summary, reportUrl}) => {
+  const columns = [
+    `[${createURL(url).pathname}](${url})`,
+
+    .../** @type {(keyof LighthouseSummary)[]} */ (
+      Object.keys(summaryKeys)
+    ).map((k) => scoreEntry(summary[k])),
+
+    // See https://github.com/facebook/docusaurus/pull/10527
+    reportUrl ? `[Report](${reportUrl})` : `Report N/A`,
+  ];
+
+  return `| ${columns.join(' | ')} |`;
+};
+
+const createMarkdownTableHeader = () => [
+  ['| URL', ...Object.values(summaryKeys), 'Report |'].join(' | '),
+  ['|---', ...Array(Object.keys(summaryKeys).length).fill('---'), '---|'].join(
+    '|',
+  ),
+];
+
+/**
+ * @param {Object} param0
+ * @param {Record<string, string>} param0.links
+ * @param {{url: string, summary: LighthouseSummary}[]} param0.results
+ */
+export default function formatLighthouseReport({results, links}) {
+  const tableHeader = createMarkdownTableHeader();
+  const tableBody = results.map((result) => {
+    const {url, summary} = result;
+    const reportUrl = /** @type {string | undefined} */ (links[result.url]);
+    return createMarkdownTableRow({
+      url,
+      summary,
+      reportUrl,
+    });
+  });
+  const comment = [
+    '### ⚡️ Lighthouse report for the deploy preview of this PR',
+    '',
+    ...tableHeader,
+    ...tableBody,
+    '',
+  ];
+  return comment.join('\n');
+}

admin/scripts/generateExamples.js

@@ -0,0 +1,206 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// @ts-check
+
+import fs from 'fs-extra';
+import shell from 'shelljs';
+
+/**
+ * Generate one example per init template
+ * We use those generated examples as CodeSandbox projects
+ * See https://github.com/facebook/docusaurus/issues/1699
+ * @param {string} template
+ */
+async function generateTemplateExample(template) {
+  try {
+    console.log(
+      `generating ${template} template for codesandbox in the examples folder...`,
+    );
+
+    // Run the docusaurus script to create the template in the examples folder
+    const command = template.endsWith('-typescript')
+      ? template.replace('-typescript', ' -- --typescript')
+      : `${template} -- --javascript`;
+
+    shell.exec(
+      // We use the published init script on purpose, because the local init is
+      // too new and could generate upcoming/unavailable config options.
+      // Remember CodeSandbox templates will use the published version,
+      // not the repo version.
+      // Using "yarn create" because "npm init" still try to use local pkg
+      `yarn create docusaurus examples/${template} ${command}`,
+    );
+
+    const templatePackageJson =
+      await /** @type {Promise<import("../../packages/create-docusaurus/templates/classic/package.json") & { scripts: { [name: string]: string }; description: string }>} */ (
+        fs.readJSON(`examples/${template}/package.json`)
+      );
+
+    // Attach the dev script which would be used in code sandbox by default
+    templatePackageJson.scripts.dev = 'docusaurus start';
+
+    // These example projects are not meant to be published to npm
+    templatePackageJson.private = true;
+
+    // Make sure package.json name is not "examples-classic". The package.json
+    // name appears in CodeSandbox UI so let's display a good name!
+    // Unfortunately we can't use uppercase or spaces... See also
+    // https://github.com/codesandbox/codesandbox-client/pull/5136#issuecomment-763521662
+    templatePackageJson.name =
+      template === 'classic' ? 'docusaurus' : `docusaurus-${template}`;
+    templatePackageJson.description =
+      template === 'classic'
+        ? 'Docusaurus example project'
+        : `Docusaurus example project (${template} template)`;
+
+    await fs.writeFile(
+      `./examples/${template}/package.json`,
+      `${JSON.stringify(templatePackageJson, null, 2)}\n`,
+    );
+
+    // Create sandbox/stackblitz config file at the root of template
+    const codeSandboxConfig = {
+      infiniteLoopProtection: true,
+      hardReloadOnChange: true,
+      view: 'browser',
+      template: 'docusaurus',
+      node: '18',
+      container: {
+        node: '18',
+      },
+    };
+    await fs.writeFile(
+      `./examples/${template}/sandbox.config.json`,
+      `${JSON.stringify(codeSandboxConfig, null, 2)}\n`,
+    );
+
+    const stackBlitzConfig = {
+      installDependencies: true,
+      startCommand: 'npm start',
+    };
+    await fs.writeFile(
+      `./examples/${template}/.stackblitzrc`,
+      `${JSON.stringify(stackBlitzConfig, null, 2)}\n`,
+    );
+
+    console.log(`Generated example for template ${template}`);
+  } catch (err) {
+    console.error(`Failed to generated example for template ${template}`);
+    throw err;
+  }
+}
+
+/**
+ * Starters are repositories/branches that only contains a newly initialized
+ * Docusaurus site. Those are useful for users to inspect (may be more
+ * convenient than "examples/classic) Also some tools like Netlify deploy button
+ * currently require using the main branch of a dedicated repo.
+ * See https://github.com/jamstack/jamstack.org/pull/609
+ * Button visible here: https://jamstack.org/generators/
+ */
+function updateStarters() {
+  /**
+   * @param {Object} param0
+   * @param {string} param0.subfolder
+   * @param {string} param0.remote
+   * @param {string} param0.remoteBranch
+   */
+  function forcePushGitSubtree({subfolder, remote, remoteBranch}) {
+    console.log('');
+    // See https://stackoverflow.com/questions/33172857/how-do-i-force-a-subtree-push-to-overwrite-remote-changes
+    const command = `git push ${remote} \`git subtree split --prefix ${subfolder}\`:${remoteBranch} --force`;
+    try {
+      console.log(`forcePushGitSubtree command: ${command}`);
+      shell.exec(command);
+      console.log('forcePushGitSubtree success!');
+    } catch (err) {
+      console.error(
+        `Can't force push to git subtree with command '${command}'`,
+      );
+      console.error(`If it's a permission problem, ask @slorber`);
+      console.error(err);
+    }
+    console.log('');
+  }
+
+  console.log('');
+
+  console.log('Updating https://github.com/facebook/docusaurus/tree/starter');
+  forcePushGitSubtree({
+    subfolder: 'examples/classic',
+    remote: 'origin',
+    remoteBranch: 'starter',
+  });
+
+  console.log('');
+  console.log('');
+
+  // TODO replace by starter repo in Docusaurus-community org (if we get it)
+  console.log('Updating https://github.com/slorber/docusaurus-starter');
+  forcePushGitSubtree({
+    subfolder: 'examples/classic',
+    remote: 'git@github.com:slorber/docusaurus-starter.git',
+    remoteBranch: 'main',
+  });
+
+  console.log('');
+}
+
+const branch = shell.exec('git rev-parse --abbrev-ref HEAD').stdout;
+if (branch === 'main') {
+  throw new Error(
+    "Please don't generate Docusaurus examples from the main branch!\nWe are going to commit during this process!",
+  );
+}
+if (shell.exec('git diff --exit-code').code !== 0) {
+  throw new Error(
+    'Please run the generate examples command with a clean Git state and no uncommitted local changes. git diff should display nothing!',
+  );
+}
+
+console.log(`
+# Generate examples start!
+`);
+
+// Delete the examples directories if they exist
+console.log(`-------
+## Removing example folders...
+`);
+await fs.rm('./examples/classic', {recursive: true, force: true});
+await fs.rm('./examples/classic-typescript', {recursive: true, force: true});
+
+// Get the list of all available templates
+console.log(`
+-------
+## Generate example folders...
+`);
+const excludes = ['README.md', 'shared'];
+const templates = (
+  await fs.readdir('./packages/create-docusaurus/templates')
+).filter((name) => !excludes.includes(name));
+console.log(`Will generate examples for templates: ${templates.join(',')}`);
+for (const template of templates) {
+  await generateTemplateExample(template);
+}
+console.log('Committing changes');
+shell.exec('git add examples');
+shell.exec("git commit -am 'update examples' --allow-empty");
+
+// Update starters
+console.log(`
+-------
+# Updating starter repos and branches ...
+It can take some time... please wait until done...
+`);
+updateStarters();
+
+console.log(`
+-------
+Generate examples end!
+Don't forget to push and merge your pull request!
+`);

admin/scripts/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "docu-scripts",
+  "description": "These are the scripts used in various places of Docusaurus maintenance",
+  "private": true,
+  "license": "MIT",
+  "type": "module"
+}

admin/scripts/resizeImage.js

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {program} from 'commander';
+import {logger} from '@docusaurus/logger';
+import sharp from 'sharp';
+import {imageSizeFromFile} from 'image-size/fromFile';
+
+// You can use it as:
+//
+// # Resize all images in showcase (which is most likely)
+// node admin/scripts/resizeImage.js
+//
+// # Resize specified images / all images in a folder
+// # This does not read folders recursively as of now
+// node admin/scripts/resizeImage.js image1.png some-folder ...
+//
+// By default, showcase images are resized to 640×320; everything else is
+// resized to width 1000. You can explicitly give a width/height as arguments.
+// node admin/scripts/resizeImage.js --width 640 --height 320 image1.png
+
+function maybeParseInt(n) {
+  const res = Number.parseInt(n, 10);
+  if (Number.isNaN(res)) {
+    return undefined;
+  }
+  return res;
+}
+
+const showcasePath = 'website/src/data/showcase';
+
+program
+  .arguments('[imagePaths...]')
+  .option('-w, --width <width>', 'Image width', maybeParseInt)
+  .option('-h, --height <height>', 'Image height', maybeParseInt)
+  .action(async (imagePaths, options) => {
+    if (imagePaths.length === 0) {
+      imagePaths.push(showcasePath);
+    }
+    const rootDir = fileURLToPath(new URL('../..', import.meta.url));
+    const images = (
+      await Promise.all(
+        imagePaths.map(async (p) =>
+          path.extname(p)
+            ? [path.resolve(rootDir, p)]
+            : (await fs.readdir(p)).map((f) => path.resolve(rootDir, p, f)),
+        ),
+      )
+    )
+      .flat()
+      .filter((p) => ['.png', 'jpg', '.jpeg'].includes(path.extname(p)));
+
+    const stats = {
+      skipped: 0,
+      resized: 0,
+    };
+
+    await Promise.all(
+      images.map(async (imgPath) => {
+        const {width, height} = await imageSizeFromFile(imgPath);
+        const targetWidth =
+          options.width ?? (imgPath.includes(showcasePath) ? 640 : 1000);
+        const targetHeight =
+          options.height ?? (imgPath.includes(showcasePath) ? 320 : undefined);
+        if (
+          width <= targetWidth &&
+          (!targetHeight || height <= targetHeight) &&
+          imgPath.endsWith('.png')
+        ) {
+          // Do not emit if not resized. Important because we can't guarantee
+          // idempotency during resize -> optimization
+          stats.skipped += 1;
+          return;
+        }
+        logger.info`Resized path=${imgPath}: before number=${width}×number=${height}; now number=${targetWidth}×number=${
+          targetHeight ?? Math.floor((height / width) * targetWidth)
+        }`;
+        const data = await sharp(imgPath)
+          .resize(targetWidth, targetHeight, {fit: 'cover', position: 'top'})
+          .png()
+          .toBuffer();
+        await fs.writeFile(imgPath.replace(/jpe?g/, 'png'), data);
+        stats.resized += 1;
+      }),
+    );
+
+    logger.info`Images resizing complete.
+        resized: number=${stats.resized}
+        skipped: number=${stats.skipped}`;
+  });
+
+program.parse(process.argv);
+
+// You should also run
+// optimizt `find website/src/data/showcase -type f -name '*.png'`.
+// This is not included here because @funboxteam/optimizt doesn't seem to play
+// well with M1 so I had to run this in a Rosetta terminal.
+// TODO integrate this as part of the script

admin/scripts/test-release.sh

@@ -5,22 +5,24 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-set -euo pipefail
+set -xeuo pipefail
+
+rm -rf ../test-website
 
 CUSTOM_REGISTRY_URL="http://localhost:4873"
-NEW_VERSION="$(node -p "require('./packages/docusaurus/package.json').version").NEW"
+NEW_VERSION="$(node -p "require('./packages/docusaurus/package.json').version")-NEW"
 CONTAINER_NAME="verdaccio"
 EXTRA_OPTS=""
 
-usage() { echo "Usage: $0 [-n] [-s]" 1>&2; exit 1; }
+usage() { echo "Usage: $0 [-s] [-t]" 1>&2; exit 1; }
 
-while getopts ":ns" o; do
+while getopts ":st" o; do
   case "${o}" in
-    n)
-      EXTRA_OPTS="--use-npm"
-      ;;
     s)
-      EXTRA_OPTS="--skip-install"
+      EXTRA_OPTS="${EXTRA_OPTS} --skip-install"
+      ;;
+    t)
+      EXTRA_OPTS="${EXTRA_OPTS} --typescript"
       ;;
     *)
       usage
@@ -51,11 +53,14 @@ git diff --name-only -- '*.json' | sed 's, ,\\&,g' | xargs git checkout --
 # The website is generated outside the repo to minimize chances of yarn resolving the wrong version
 cd ..
 
+echo Generating test-website in `pwd`
+
 # Build skeleton website with new version
-npm_config_registry="$CUSTOM_REGISTRY_URL" npm init docusaurus@"$NEW_VERSION" test-website classic $EXTRA_OPTS
+npm_config_registry="$CUSTOM_REGISTRY_URL" npx --yes --loglevel silly create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+
 
 # Stop Docker container
-if [[ -z "${KEEP_CONTAINER:-}" ]] && ( $(docker container inspect "$CONTAINER_NAME" > /dev/null 2>&1) ); then
+if [[ -z "${KEEP_CONTAINER:-true}" ]] && ( $(docker container inspect "$CONTAINER_NAME" > /dev/null 2>&1) ); then
   # Remove Docker container
   docker container stop $CONTAINER_NAME > /dev/null
 fi

admin/test-bad-package/README.mdx

@@ -0,0 +1,49 @@
+# test-bad-package
+
+This package declares a wrong React version on purpose (16.14.0)
+
+The goal is to test that the MD/MDX content of this package can still be imported/rendered by our website.
+
+See related issue https://github.com/facebook/docusaurus/issues/9027
+
+---
+
+import {version as ReactVersion} from 'react';
+import {version as ReactDOMVersion} from 'react-dom';
+
+export function TestComponent() {
+  const expectedVersion = 19;
+  if (!ReactVersion.startsWith(`${expectedVersion}`)) {
+    throw new Error(
+      `'test-bad-package/README.mdx' is rendered with bad React version: ${ReactVersion}`,
+    );
+  }
+  if (!ReactVersion.startsWith(`${expectedVersion}`)) {
+    throw new Error(
+      `'test-bad-package/README.mdx' is rendered with bad React-DOM version: ${ReactDOMVersion}`,
+    );
+  }
+  return (
+    <>
+      <div>React version: {ReactVersion}</div>
+      <div>React DOM version: {ReactDOMVersion}</div>
+    </>
+  );
+}
+
+<TestComponent />
+
+---
+
+## MDX Components work:
+
+<details>
+  <summary>Summary</summary>
+
+Details
+
+</details>
+
+```js
+const age = 42;
+```

admin/test-bad-package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "test-bad-package",
+  "version": "3.9.2",
+  "private": true,
+  "dependencies": {
+    "@mdx-js/react": "1.0.1",
+    "react": "16.14.0",
+    "react-dom": "16.14.0"
+  }
+}

admin/testing-changes-on-Docusaurus-itself.md

@@ -17,7 +17,7 @@ yarn start
 
 ### VS Code
 
-Use the following code in VSCode to enable breakpoints. Please ensure you have a later version of node for non-legacy debugging.
+Use the following code in VS Code to enable breakpoints. Please ensure you have a later version of node for non-legacy debugging.
 
 ```json
 {

admin/verdaccio.yaml

@@ -13,11 +13,30 @@
 
 storage: ../storage
 
+# Verdaccio does not allow to publish packages when the client is offline, to avoid
+# errors on publish
+# https://verdaccio.org/docs/configuration#offline-publish
+publish:
+  allow_offline: false
+
 # A list of other known repositories we can talk to
 uplinks:
   npmjs:
     url: https://registry.npmjs.org/
 packages:
+  # Forked packages need to be fetched from npm
+  '@docusaurus/react-loadable':
+    access: $all
+    publish: $all
+    proxy: npmjs
+  # Group and isolate all local packages, avoid being proxy from outside
+  '@docusaurus/*':
+    access: $all
+    publish: $all
+  '@*/*':
+    access: $all
+    publish: $authenticated
+    proxy: npmjs
   '**':
     # Allow all users (including non-authenticated users) to read and
     # publish all packages

argos/.gitignore

@@ -0,0 +1,5 @@
+
+/screenshots/
+/test-results/
+/playwright-report/
+/playwright/.cache/

argos/README.md

@@ -0,0 +1,21 @@
+# Argos visual regression tests
+
+We use [Argos CI](https://argos-ci.com) to detect visual regressions on Docusaurus.
+
+This workspace can be run manually, but is generally run through the [Argos GitHub Action](../.github/workflows/argos.yml).
+
+The workflow execute those following steps:
+
+- Build the website locally with `yarn build:website:fast`
+- Start the website server with `yarn serve:website` on [http://localhost:3000](http://localhost:3000)
+- Take screenshots of all pages found in `sitemap.xml` with Playwright
+- Upload all screenshots to [Argos CI](https://argos-ci.com)
+
+This workflow runs for `main` and PR branches, and add a commit status to each PR with a visual diff that we can easily inspect.
+
+---
+
+Some additional capabilities:
+
+- Use [./tests/screenshot.spec.ts](./tests/screenshot.spec.ts) to customize the screenshots we take, eventually filter out some useless sitemap pages like versioned docs
+- Use [./tests/screenshot.css](./tests/screenshot.css) to hide flaky CSS elements: iframe, video, gif...

argos/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "argos",
+  "version": "3.9.2",
+  "description": "Argos visual diff tests",
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "screenshot": "playwright test",
+    "upload": "npx @argos-ci/cli upload ./screenshots/chromium",
+    "report": "playwright show-report"
+  },
+  "dependencies": {
+    "@argos-ci/playwright": "^2.0.0",
+    "@playwright/test": "^1.48.1",
+    "cheerio": "1.0.0-rc.12"
+  }
+}

argos/playwright.config.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {devices} from '@playwright/test';
+import type {PlaywrightTestConfig} from '@playwright/test';
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+const config: PlaywrightTestConfig = {
+  testDir: './tests',
+
+  timeout: 60000,
+
+  reporter: [['list'], ['@argos-ci/playwright/reporter']],
+
+  // Run website production built
+  // Need to run "yarn website:build:fast" before
+  webServer: {
+    cwd: '..',
+    port: 3000,
+    command: 'yarn serve:website',
+  },
+
+  // Browsers: only Chrome for now
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+};
+
+export default config;

argos/tests/screenshot.css

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/*
+We need to hide some elements in Argos/Playwright screenshots
+Those elements are source of flakiness due to nondeterministic rendering
+They don't consistently render exactly the same across CI runs
+ */
+
+/******* DOCUSAURUS GLOBAL / THEME *******/
+
+/* Iframes can load lazily */
+iframe,
+/* Avatar images can be flaky due to using external sources: GitHub/Unavatar */
+.avatar__photo,
+/* Gifs load lazily and are animated */
+img[src$='.gif'],
+/* Algolia Keyboard shortcuts appear with a little delay */
+.DocSearch-Button-Keys > kbd,
+/* The live playground preview can often display dates/counters */
+[class*='playgroundPreview'] {
+  visibility: hidden;
+}
+
+/*
+Different docs last-update dates can alter layout
+"visibility: hidden" is not enough
+ */
+.theme-last-updated {
+  display: none;
+}
+
+/*
+Mermaid diagrams are rendered client-side and produce layout shifts
+ */
+.docusaurus-mermaid-container {
+  display: none;
+}
+
+/******* DOCUSAURUS WEBSITE SPECIFIC *******/
+
+/* ProductHunt vote counter can increment at any time */
+.producthunt-badge-widget {
+  visibility: hidden;
+}
+
+/* YouTube player lite can load video lazily */
+article.yt-lite {
+  visibility: hidden;
+}

argos/tests/screenshot.spec.ts

@@ -0,0 +1,183 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import * as fs from 'fs';
+import {test} from '@playwright/test';
+import {argosScreenshot} from '@argos-ci/playwright';
+import * as cheerio from 'cheerio';
+import type {Page} from '@playwright/test';
+
+const siteUrl = 'http://localhost:3000';
+const sitemapPath = '../website/build/sitemap.xml';
+const stylesheetPath = './tests/screenshot.css';
+
+// Use ONLY_PATH="/docs/installation" to debug a specific page
+const onlyPath: string | undefined = process.env.ONLY_PATH;
+
+// eslint-disable-next-line no-restricted-properties
+const sitemap = fs.readFileSync(sitemapPath).toString();
+// eslint-disable-next-line no-restricted-properties
+const stylesheet = fs.readFileSync(stylesheetPath).toString();
+
+function extractSitemapUrls() {
+  const $ = cheerio.load(sitemap, {xmlMode: true});
+  const urls: string[] = [];
+  $('loc').each(function handleLoc() {
+    urls.push($(this).text());
+  });
+  return urls;
+}
+
+function isBlacklisted(pathname: string) {
+  if (onlyPath && onlyPath !== pathname) {
+    return true;
+  }
+  // Some paths explicitly blacklisted
+  const BlacklistedPathnames: string[] = [
+    // Flaky because of Canny widget
+    '/feature-requests',
+    // Flaky because of dynamic canary version fetched from npm
+    '/community/canary',
+    // Flaky because of screenshots being taken dynamically
+    '/showcase',
+    // Long blog post with many image carousels, often timeouts
+    '/blog/2022/08/01/announcing-docusaurus-2.0',
+
+    // DOGFOOD TESTS
+    // React key errors:
+    '/tests/docs/tests/toc-partials',
+    // Console errors
+    '/tests/pages/diagrams',
+    '/tests/pages/markdown-tests-md',
+    '/tests/pages/react-18',
+    // Flaky because of hydration error
+    '/tests/blog/archive',
+    '/tests/pages/code-block-tests',
+    '/tests/pages/embeds',
+    // Flaky because of hydration error with docusaurus serve + .html
+    '/tests/blog/x/y/z.html',
+    '/tests/docs/dummy.html',
+    // Cause weird docusaurus serve errors:
+    '/tests/docs/tests/ascii/%C3%A6%C3%B8%C3%A5',
+    '/tests/docs/tests/ascii/folder/%C3%A6%C3%B8%C3%A5',
+  ];
+
+  return (
+    // changelog docs
+    pathname.startsWith('/changelog') ||
+    // versioned docs
+    pathname.match(/^\/docs\/((\d\.\d\.\d)|(next))\//) ||
+    // verbose useless dogfooding pages
+    pathname.startsWith('/tests/docs/toc/') ||
+    pathname.startsWith('/tests/docs/tags/') ||
+    pathname.startsWith('/tests/docs/tests/category-links') ||
+    pathname.startsWith('/tests/docs/tests/visibility') ||
+    pathname.startsWith('/tests/blog/page/') ||
+    pathname.startsWith('/tests/blog/tags/') ||
+    // manually excluded urls
+    BlacklistedPathnames.includes(pathname)
+  );
+}
+
+function getPathnames(): string[] {
+  const urls = extractSitemapUrls();
+  const pathnamesUnfiltered = urls.map((url) => new URL(url).pathname);
+  const pathnames = pathnamesUnfiltered.filter(
+    (pathname) => !isBlacklisted(pathname),
+  );
+  pathnames.sort();
+  /*
+  console.log('Pathnames:\n', JSON.stringify(pathnames, null, 2));
+  console.log('Pathnames before filtering', pathnamesUnfiltered.length);
+  console.log('Pathnames after filtering', pathnames.length);
+
+   */
+  return pathnames;
+}
+
+function pathnameToArgosName(pathname: string): string {
+  function removeTrailingSlash(str: string): string {
+    return str.endsWith('/') ? str.slice(0, -1) : str;
+  }
+  function removeLeadingSlash(str: string): string {
+    return str.startsWith('/') ? str.slice(1) : str;
+  }
+
+  pathname = removeTrailingSlash(pathname);
+  pathname = removeLeadingSlash(pathname);
+
+  if (pathname === '') {
+    return 'index';
+  }
+
+  return pathname;
+}
+
+// See https://github.com/facebook/docusaurus/pull/9256
+// Docusaurus adds a <html data-has-hydrated="true">
+function waitForDocusaurusHydration() {
+  return document.documentElement.dataset.hasHydrated === 'true';
+}
+
+// Ensure that Docusaurus site pages do not emit unexpected errors/warnings
+// See https://github.com/microsoft/playwright/issues/27277
+// TODO this shouldn't be the responsibility of Argos tests to do this
+//  but this is convenient to do this here for now
+function throwOnConsole(page: Page) {
+  const typesToCheck = ['error', 'warning'];
+
+  const ignoreMessages = [
+    // TODO this fetch error message is unexpected and should be fixed
+    //  it's already happening in main branch
+    'Failed to load resource: the server responded with a status of 404 (Not Found)',
+
+    // Warning because react-live not supporting React automatic JSX runtime
+    // See https://github.com/FormidableLabs/react-live/issues/405
+    'Your app (or one of its dependencies) is using an outdated JSX transform. Update to the modern JSX transform for faster performance',
+
+    // TODO weird problem related to KaTeX fonts refusing to decode?
+    //  on /docs/markdown-features/math-equations
+    'Failed to decode downloaded font: http://localhost:3000/katex/fonts/',
+    'OTS parsing error: Failed to convert WOFF 2.0 font to SFNT',
+
+    // Mermaid warning, see https://github.com/mermaid-js/mermaid/issues/6031
+    'Do not assign mappings to elements without corresponding data',
+  ];
+
+  page.on('console', (message) => {
+    if (!typesToCheck.includes(message.type())) {
+      return;
+    }
+    if (ignoreMessages.some((msg) => message.text().includes(msg))) {
+      return;
+    }
+    throw new Error(`Docusaurus site page unexpectedly logged something to the browser console
+Type=${message.type()}
+Text=${message.text()}
+Location=${message.location().url}`);
+  });
+}
+
+function createPathnameTest(pathname: string) {
+  test(`pathname ${pathname}`, async ({page}) => {
+    throwOnConsole(page);
+    const url = siteUrl + pathname;
+    await page.goto(url);
+    await page.waitForFunction(waitForDocusaurusHydration);
+    await page.addStyleTag({content: stylesheet});
+    // await expect(page).toHaveScreenshot({ fullPage: true, ...options });
+    await argosScreenshot(page, pathnameToArgosName(pathname));
+  });
+}
+
+// Allow parallel execution within a single test file
+// See https://playwright.dev/docs/test-parallel
+test.describe.configure({mode: 'parallel'});
+
+test.describe('Docusaurus site screenshots', () => {
+  const pathnames = getPathnames();
+  pathnames.forEach(createPathnameTest);
+});

babel.config.js

@@ -1,27 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-module.exports = {
-  presets: [
-    [
-      '@babel/env',
-      {
-        targets: {
-          node: 'current',
-        },
-      },
-    ],
-    '@babel/react',
-    '@babel/preset-typescript',
-  ],
-  plugins: [
-    '@babel/plugin-proposal-class-properties',
-    '@babel/plugin-proposal-object-rest-spread',
-    '@babel/plugin-proposal-nullish-coalescing-operator',
-    '@babel/plugin-proposal-optional-chaining',
-  ],
-};

crowdin-v2.yaml

@@ -2,9 +2,9 @@
 # Your Crowdin credentials
 #
 project_id: '428890'
-api_token_env: 'CROWDIN_PERSONAL_TOKEN'
+api_token_env: CROWDIN_PERSONAL_TOKEN
 # base_path: '.'
-# base_url: 'https://api.crowdin.com'
+# base_url: https://api.crowdin.com
 
 #
 # Choose file structure in Crowdin
@@ -18,45 +18,59 @@ preserve_hierarchy: true
 # Note: &/* is Yaml anchor syntax: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
 languages_mapping: &languages_mapping
   two_letters_code:
-    'pt-BR': 'pt-BR'
+    pt-BR: pt-BR
+
+# Crowdin regularly update their MDX parser
+# Unfortunately, their v2 parser is more "MDX compliant" and thus can't parse
+# Docusaurus MDX files correctly due to our custom {#headingId} syntax.
+# Adding this type param permits using their older v1.2 parser.
+# Note: you can find the version of a file using browser DevTools
+# The source file icons will have a class such as "file_type_mdx_v1_2"
+#
+# TODO fix our headingId syntax
+# providing an explicit type is annoying and not future-proof
+# there's a risk that when adding an image in /docs, it will be parsed as mdx
+# and duplicating source file configs for various extensions is not great either
+mdx_file_type: &mdx_file_type mdx_v1_2
 
 #
 # Files configuration
 #
 files:
-  [
-    {
-      source: '/website/i18n/en/**/*',
-      translation: '/website/i18n/%two_letters_code%/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/docs/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/community/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/versioned_docs/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/blog/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%',
-      languages_mapping: *languages_mapping,
-    },
-    {
-      source: '/website/src/pages/**/*',
-      translation: '/website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%',
-      ignore: ['/**/*.js', '/**/*.jsx', '/**/*.ts', '/**/*.tsx', '/**/*.css'],
-      languages_mapping: *languages_mapping,
-    },
-  ]
+  - source: /website/i18n/en/**/*
+    translation: /website/i18n/%two_letters_code%/**/%original_file_name%
+    languages_mapping: *languages_mapping
+
+  - source: /website/docs/**/*.mdx
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+    type: *mdx_file_type
+  - source: /website/docs/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+    ignore: [/**/*.mdx]
+
+  - source: /website/versioned_docs/**/*.mdx
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
+    languages_mapping: *languages_mapping
+    type: *mdx_file_type
+  - source: /website/versioned_docs/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
+    languages_mapping: *languages_mapping
+    ignore: [/**/*.mdx]
+
+  - source: /website/community/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+
+  - source: /website/blog/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
+    languages_mapping: *languages_mapping
+
+  - source: /website/src/pages/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%
+    ignore: [/**/*.js, /**/*.jsx, /**/*.ts, /**/*.tsx, /**/*.css]
+    languages_mapping: *languages_mapping
 #
 # Source files filter
 # e.g. "/resources/en/*.json"

examples/README.md

@@ -2,15 +2,14 @@
 
 These example projects are generated with the init CLI:
 
-```
+```bash
 npx @docusaurus/init@latest init examples/<templateName> <templateName>`
 ```
 
 You can run them in CodeSandbox:
 
 - [classic](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/classic)
-- [bootstrap](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/bootstrap)
-- [facebook](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/facebook)
+- [classic-typescript](https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/classic-typescript)
 
 **Tip**: use the [new.docusaurus.io](https://new.docusaurus.io) shortcut.
 

examples/classic-typescript/.stackblitzrc

@@ -1,4 +1,4 @@
 {
   "installDependencies": true,
   "startCommand": "npm start"
-}
+}

examples/classic-typescript/README.md

@@ -1,33 +1,41 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Installation
+## Installation
 
-```
-$ yarn
+```bash
+yarn
 ```
 
-### Local Development
+## Local Development
 
-```
-$ yarn start
+```bash
+yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-### Build
+## Build
 
-```
-$ yarn build
+```bash
+yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+## Deployment
 
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
 ```
-$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

examples/classic-typescript/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

examples/classic-typescript/blog/2019-05-28-first-blog-post.md

@@ -1,12 +1,12 @@
 ---
 slug: first-blog-post
 title: First Blog Post
-authors:
-  name: Gao Wei
-  title: Docusaurus Core Team
-  url: https://github.com/wgao19
-  image_url: https://github.com/wgao19.png
+authors: [slorber, yangshun]
 tags: [hola, docusaurus]
 ---
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+Lorem ipsum dolor sit amet...
+
+<!-- truncate -->
+
+...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

examples/classic-typescript/blog/2019-05-29-long-blog-post.md

@@ -1,7 +1,7 @@
 ---
 slug: long-blog-post
 title: Long Blog Post
-authors: endi
+authors: yangshun
 tags: [hello, docusaurus]
 ---
 
@@ -9,7 +9,7 @@ This is the summary of a very long blog post,
 
 Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
 
-<!--truncate-->
+<!-- truncate -->
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
 

examples/classic-typescript/blog/2021-08-01-mdx-blog-post.mdx

@@ -11,10 +11,14 @@ Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/mar
 
 Use the power of React to create interactive blog posts.
 
+:::
+
+{/* truncate */}
+
+For example, use JSX to create an interactive button:
+
 ```js
 <button onClick={() => alert('button clicked!')}>Click me!</button>
 ```
 
 <button onClick={() => alert('button clicked!')}>Click me!</button>
-
-:::

examples/classic-typescript/blog/2021-08-26-welcome/index.md

@@ -7,6 +7,10 @@ tags: [facebook, hello, docusaurus]
 
 [Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
 
+Here are a few tips you might find useful.
+
+<!-- truncate -->
+
 Simply add Markdown files (or folders) to the `blog` directory.
 
 Regular blog authors can be added to `authors.yml`.

examples/classic-typescript/blog/authors.yml

@@ -1,17 +1,25 @@
-endi:
-  name: Endilie Yacop Sucipto
-  title: Maintainer of Docusaurus
-  url: https://github.com/endiliey
-  image_url: https://github.com/endiliey.png
-
 yangshun:
   name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  url: https://linkedin.com/in/yangshun
   image_url: https://github.com/yangshun.png
+  page: true
+  socials:
+    x: yangshunz
+    linkedin: yangshun
+    github: yangshun
+    newsletter: https://www.greatfrontend.com
 
 slorber:
   name: Sébastien Lorber
   title: Docusaurus maintainer
   url: https://sebastienlorber.com
   image_url: https://github.com/slorber.png
+  page:
+    # customize the url of the author page at /blog/authors/<permalink>
+    permalink: '/all-sebastien-lorber-articles'
+  socials:
+    x: sebastienlorber
+    linkedin: sebastienlorber
+    github: slorber
+    newsletter: https://thisweekinreact.com

examples/classic-typescript/blog/tags.yml

@@ -0,0 +1,19 @@
+facebook:
+  label: Facebook
+  permalink: /facebook
+  description: Facebook tag description
+
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description
+
+docusaurus:
+  label: Docusaurus
+  permalink: /docusaurus
+  description: Docusaurus tag description
+
+hola:
+  label: Hola
+  permalink: /hola
+  description: Hola tag description

examples/classic-typescript/docs/intro.md

@@ -12,24 +12,36 @@ Get started by **creating a new site**.
 
 Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
 
+### What you'll need
+
+- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
+  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+
 ## Generate a new site
 
-Generate a new Docusaurus site using the **classic template**:
+Generate a new Docusaurus site using the **classic template**.
 
-```shell
+The classic template will automatically be added to your project after you run the command:
+
+```bash
 npm init docusaurus@latest my-website classic
 ```
 
+You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+
+The command also installs all necessary dependencies you need to run Docusaurus.
+
 ## Start your site
 
 Run the development server:
 
-```shell
+```bash
 cd my-website
-
-npx docusaurus start
+npm run start
 ```
 
-Your site starts at `http://localhost:3000`.
+The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
 
-Open `docs/intro.md` and edit some lines: the site **reloads automatically** and display your changes.
+The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+
+Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.

examples/classic-typescript/docs/tutorial-basics/_category_.json

@@ -1,4 +1,8 @@
 {
   "label": "Tutorial - Basics",
-  "position": 2
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "5 minutes to learn the most important Docusaurus concepts."
+  }
 }

examples/classic-typescript/docs/tutorial-basics/congratulations.md

@@ -14,7 +14,9 @@ Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://
 
 ## What's next?
 
-- Read the [official documentation](https://docusaurus.io/).
+- Read the [official documentation](https://docusaurus.io/)
+- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config)
+- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration)
 - Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
 - Add a [search bar](https://docusaurus.io/docs/search)
 - Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)

examples/classic-typescript/docs/tutorial-basics/create-a-blog-post.md

@@ -28,7 +28,7 @@ tags: [greetings]
 
 Congratulations, you have made your first post!
 
-Feel free to play around and edit this post as much you like.
+Feel free to play around and edit this post as much as you like.
 ```
 
-A new blog post is now available at `http://localhost:3000/blog/greetings`.
+A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

examples/classic-typescript/docs/tutorial-basics/create-a-document.md

@@ -12,7 +12,7 @@ Documents are **groups of pages** connected through:
 
 ## Create your first Doc
 
-Create a markdown file at `docs/hello.md`:
+Create a Markdown file at `docs/hello.md`:
 
 ```md title="docs/hello.md"
 # Hello
@@ -20,7 +20,7 @@ Create a markdown file at `docs/hello.md`:
 This is my **first Docusaurus document**!
 ```
 
-A new document is now available at `http://localhost:3000/docs/hello`.
+A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello).
 
 ## Configure the Sidebar
 
@@ -41,14 +41,16 @@ This is my **first Docusaurus document**!
 
 It is also possible to create your sidebar explicitly in `sidebars.js`:
 
-```diff title="sidebars.js"
-module.exports = {
+```js title="sidebars.js"
+export default {
   tutorialSidebar: [
+    'intro',
+    // highlight-next-line
+    'hello',
     {
       type: 'category',
       label: 'Tutorial',
--     items: [...],
-+     items: ['hello'],
+      items: ['tutorial-basics/create-a-document'],
     },
   ],
 };

examples/classic-typescript/docs/tutorial-basics/create-a-page.md

@@ -6,9 +6,9 @@ sidebar_position: 1
 
 Add **Markdown or React** files to `src/pages` to create a **standalone page**:
 
-- `src/pages/index.js` -> `localhost:3000/`
-- `src/pages/foo.md` -> `localhost:3000/foo`
-- `src/pages/foo/bar.js` -> `localhost:3000/foo/bar`
+- `src/pages/index.js` → `localhost:3000/`
+- `src/pages/foo.md` → `localhost:3000/foo`
+- `src/pages/foo/bar.js` → `localhost:3000/foo/bar`
 
 ## Create your first React Page
 
@@ -28,7 +28,7 @@ export default function MyReactPage() {
 }
 ```
 
-A new page is now available at `http://localhost:3000/my-react-page`.
+A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page).
 
 ## Create your first Markdown Page
 
@@ -40,4 +40,4 @@ Create a file at `src/pages/my-markdown-page.md`:
 This is a Markdown page
 ```
 
-A new page is now available at `http://localhost:3000/my-markdown-page`.
+A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page).

examples/classic-typescript/docs/tutorial-basics/deploy-your-site.md

@@ -26,6 +26,6 @@ Test your production build locally:
 npm run serve
 ```
 
-The `build` folder is now served at `http://localhost:3000/`.
+The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/).
 
 You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).

examples/classic-typescript/docs/tutorial-basics/markdown-features.mdx

@@ -43,7 +43,7 @@ Let's see how to [Create a page](./create-a-page.md).
 
 Regular Markdown images are supported.
 
-Add an image at `static/img/docusaurus.png` and display it in Markdown:
+You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):
 
 ```md
 ![Docusaurus logo](/img/docusaurus.png)
@@ -51,17 +51,23 @@ Add an image at `static/img/docusaurus.png` and display it in Markdown:
 
 ![Docusaurus logo](/img/docusaurus.png)
 
+You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
+
+```md
+![Docusaurus logo](./img/docusaurus.png)
+```
+
 ## Code Blocks
 
 Markdown code blocks are supported with Syntax highlighting.
 
-    ```jsx title="src/components/HelloDocusaurus.js"
-    function HelloDocusaurus() {
-        return (
-            <h1>Hello, Docusaurus!</h1>
-        )
-    }
-    ```
+````md
+```jsx title="src/components/HelloDocusaurus.js"
+function HelloDocusaurus() {
+  return <h1>Hello, Docusaurus!</h1>;
+}
+```
+````
 
 ```jsx title="src/components/HelloDocusaurus.js"
 function HelloDocusaurus() {
@@ -73,17 +79,19 @@ function HelloDocusaurus() {
 
 Docusaurus has a special syntax to create admonitions and callouts:
 
-    :::tip My tip
+```md
+:::tip My tip
 
-    Use this awesome feature option
+Use this awesome feature option
 
-    :::
+:::
 
-    :::danger Take care
+:::danger Take care
 
-    This action is dangerous
+This action is dangerous
 
-    :::
+:::
+```
 
 :::tip My tip
 

examples/classic-typescript/docs/tutorial-extras/_category_.json

@@ -1,4 +1,7 @@
 {
   "label": "Tutorial - Extras",
-  "position": 3
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
 }

examples/classic-typescript/docs/tutorial-extras/manage-docs-versions.md

@@ -28,7 +28,7 @@ To navigate seamlessly across versions, add a version dropdown.
 Modify the `docusaurus.config.js` file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -45,7 +45,7 @@ module.exports = {
 
 The docs version dropdown appears in your navbar:
 
-![Docs Version Dropdown](/img/tutorial/docsVersionDropdown.png)
+![Docs Version Dropdown](./img/docsVersionDropdown.png)
 
 ## Update an existing version
 

examples/classic-typescript/docs/tutorial-extras/translate-your-site.md

@@ -11,7 +11,7 @@ Let's translate `docs/intro.md` to French.
 Modify `docusaurus.config.js` to add support for the `fr` locale:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fr'],
@@ -39,11 +39,11 @@ Start your site on the French locale:
 npm run start -- --locale fr
 ```
 
-Your localized site is accessible at `http://localhost:3000/fr/` and the `Getting Started` page is translated.
+Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated.
 
 :::caution
 
-In development, you can only use one locale at a same time.
+In development, you can only use one locale at a time.
 
 :::
 
@@ -54,7 +54,7 @@ To navigate seamlessly across languages, add a locale dropdown.
 Modify the `docusaurus.config.js` file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -71,7 +71,7 @@ module.exports = {
 
 The locale dropdown now appears in your navbar:
 
-![Locale Dropdown](/img/tutorial/localeDropdown.png)
+![Locale Dropdown](./img/localeDropdown.png)
 
 ## Build your localized site