Merge branch 'main' into ozaki/showcase

2025-08-02 00:09:48 +02:00 · 2024-04-20 18:05:11 +02:00 · 2024-04-20 18:05:11 +02:00 · 7869eb94f9
commit 7869eb94f9
parent 8c1770b44e f88da6c66d
87 changed files with 562 additions and 511 deletions
--- a/.eslintrc.js
+++ b/.eslintrc.js
@ -32,7 +32,7 @@ module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    // tsconfigRootDir: __dirname,
-    // project: ['./tsconfig.json', './website/tsconfig.json'],
+    // project: ['./tsconfig.base.json', './website/tsconfig.base.json'],
  },
  globals: {
    JSX: true,
--- a/.github/workflows/lint-autofix.yml
+++ b/.github/workflows/lint-autofix.yml
@ -39,6 +39,9 @@ jobs:
      - name: AutoFix Spelling
        run: yarn lint:spelling:fix

+      - name: Print Diff
+        run: git diff
+
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'refactor: apply lint autofix'
--- a/.github/workflows/tests-e2e.yml
+++ b/.github/workflows/tests-e2e.yml
@ -10,7 +10,7 @@ on:
      - yarn.lock
      - jest.config.mjs
      - packages/**
-      - tsconfig.json
+      - tsconfig.*.json
  pull_request:
    branches:
      - main
@ -20,7 +20,7 @@ on:
      - yarn.lock
      - jest.config.mjs
      - packages/**
-      - tsconfig.json
+      - tsconfig.*.json
      - admin/verdaccio.yaml
      - .github/workflows/tests-e2e.yml

@ -114,11 +114,27 @@ jobs:
        working-directory: ../test-website
        env:
          E2E_TEST: true
-      - name: Type check
+
+      - name: TypeCheck website
        # TODO: there're some lingering issues with PnP + tsc. Enable tsc in PnP later.
        if: matrix.variant == '-st' && matrix.nodeLinker != 'pnp'
-        run: yarn typecheck
        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
        working-directory: ../test-website
--- a/.github/workflows/tests-windows.yml
+++ b/.github/workflows/tests-windows.yml
@ -10,7 +10,7 @@ on:
      - yarn.lock
      - jest.config.mjs
      - packages/**
-      - tsconfig.json
+      - tsconfig.*.json

 concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@ -52,5 +52,14 @@ jobs:
        run: yarn workspace website test:swizzle:wrap:ts
      - name: Docusaurus Build
        run: yarn build:website:fast
+
      - name: TypeCheck website
        run: yarn workspace website typecheck
+      - name: TypeCheck website - min version - v5.1
+        run: |
+          yarn workspace website add typescript@5.1.6 --exact
+          yarn workspace website typecheck
+      - name: TypeCheck website - max version - Latest
+        run: |
+          yarn workspace website add typescript@latest --exact
+          yarn workspace website typecheck
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@ -10,7 +10,7 @@ on:
      - yarn.lock
      - jest.config.mjs
      - packages/**
-      - tsconfig.json
+      - tsconfig.*.json

 concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@ -39,9 +39,18 @@ jobs:
        run: yarn
      - name: Test
        run: yarn test
-      - name: TypeCheck website
-        run: yarn workspace website typecheck
      - name: Remove Theme Internal Re-export
        run: yarn workspace @docusaurus/theme-common removeThemeInternalReexport
      - name: Docusaurus Build
        run: yarn build:website:fast
+
+      - name: TypeCheck website
+        run: yarn workspace website typecheck
+      - name: TypeCheck website - min version - v5.1
+        run: |
+          yarn workspace website add typescript@5.1.6 --exact
+          yarn workspace website typecheck
+      - name: TypeCheck website - max version - Latest
+        run: |
+          yarn workspace website add typescript@latest --exact
+          yarn workspace website typecheck
--- a/tests/validate-tsconfig.test.ts
+++ b/tests/validate-tsconfig.test.ts
@ -31,38 +31,37 @@ async function getTsconfigFiles(): Promise<TsconfigFile[]> {
 }

 const tsconfigSchema = Joi.object({
-  extends: '../../tsconfig.json',
-  compilerOptions: Joi.alternatives().conditional(
-    Joi.object({noEmit: true}).unknown(),
-    {
-      then: Joi.object({
-        noEmit: Joi.valid(true).required(),
-        incremental: Joi.forbidden(),
-        tsBuildInfoFile: Joi.forbidden(),
-        outDir: Joi.forbidden(),
-      }).unknown(),
-      otherwise: Joi.object({
-        noEmit: Joi.valid(false).required(),
-        incremental: Joi.valid(true).required(),
-        rootDir: Joi.valid('src').required(),
-        outDir: Joi.valid('lib').required(),
-      }).unknown(),
-    },
+  extends: Joi.valid(
+    '../../tsconfig.base.json',
+    '../../tsconfig.base.client.json',
  ),
+  compilerOptions: Joi.object({
+    rootDir: Joi.valid('src').required(),
+    outDir: Joi.valid('lib').required(),
+    tsBuildInfoFile: Joi.valid(
+      'lib/.tsbuildinfo',
+      'lib/.tsbuildinfo-client',
+      'lib/.tsbuildinfo-worker',
+    ),
+  }).unknown(),
 }).unknown();

 describe('tsconfig files', () => {
  it('contain all required fields', async () => {
    const tsconfigFiles = await getTsconfigFiles();
-    tsconfigFiles.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;
-      }
-    });
+
+    tsconfigFiles
+      // Ignore noEmit configs
+      .filter((file) => !(file.content.compilerOptions!.noEmit === true))
+      .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;
+        }
+      });
  });
 });
--- a/package.json
+++ b/package.json
@ -53,7 +53,7 @@
    "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
    "lint:js:fix": "yarn lint:js --fix",
    "lint:spelling": "cspell \"**\" --no-progress --show-context --show-suggestions",
-    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | sort --ignore-case >> project-words.txt",
+    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=en_US.UTF-8 sort --ignore-case >> project-words.txt",
    "lint:style": "stylelint \"**/*.css\"",
    "lint:style:fix": "yarn lint:style --fix",
    "lerna": "lerna",
--- a/packages/create-docusaurus/tsconfig.build.json
+++ b/packages/create-docusaurus/tsconfig.build.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "composite": true,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/create-docusaurus/tsconfig.json
+++ b/packages/create-docusaurus/tsconfig.json
@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.build.json"}],
  "compilerOptions": {
    "noEmit": true,
--- a/packages/docusaurus-cssnano-preset/tsconfig.json
+++ b/packages/docusaurus-cssnano-preset/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-logger/tsconfig.json
+++ b/packages/docusaurus-logger/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus-mdx-loader/tsconfig.json
+++ b/packages/docusaurus-mdx-loader/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus-plugin-client-redirects/tsconfig.json
+++ b/packages/docusaurus-plugin-client-redirects/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-content-blog/tsconfig.client.json
+++ b/packages/docusaurus-plugin-content-blog/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/client", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-content-blog/tsconfig.json
+++ b/packages/docusaurus-plugin-content-blog/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-content-docs/src/tests/index.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/index.test.ts
@ -58,7 +58,7 @@ Available ids are:\n- ${version.docs.map((d) => d.id).join('\n- ')}`,
 }

 const createFakeActions = (contentDir: string) => {
-  const routeConfigs: RouteConfig[] = [];
+  let routeConfigs: RouteConfig[] = [];
  const dataContainer: {[key: string]: unknown} = {};
  const globalDataContainer: {pluginName?: {pluginId: unknown}} = {};

@ -83,7 +83,7 @@ const createFakeActions = (contentDir: string) => {
    expectSnapshot: () => {
      // Sort the route config like in src/server/plugins/index.ts for
      // consistent snapshot ordering
-      sortRoutes(routeConfigs);
+      routeConfigs = sortRoutes(routeConfigs, '/');
      expect(routeConfigs).not.toEqual([]);
      expect(routeConfigs).toMatchSnapshot('route config');
      expect(dataContainer).toMatchSnapshot('data');
--- a/packages/docusaurus-plugin-content-docs/tsconfig.client.json
+++ b/packages/docusaurus-plugin-content-docs/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/client", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-content-docs/tsconfig.json
+++ b/packages/docusaurus-plugin-content-docs/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-content-pages/tsconfig.json
+++ b/packages/docusaurus-plugin-content-pages/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-debug/tsconfig.client.json
+++ b/packages/docusaurus-plugin-debug/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/theme", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-debug/tsconfig.json
+++ b/packages/docusaurus-plugin-debug/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-google-analytics/tsconfig.client.json
+++ b/packages/docusaurus-plugin-google-analytics/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/analytics.ts", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-google-analytics/tsconfig.json
+++ b/packages/docusaurus-plugin-google-analytics/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-google-gtag/tsconfig.client.json
+++ b/packages/docusaurus-plugin-google-gtag/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/gtag.ts", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-google-gtag/tsconfig.json
+++ b/packages/docusaurus-plugin-google-gtag/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json
+++ b/packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-google-tag-manager/tsconfig.json
+++ b/packages/docusaurus-plugin-google-tag-manager/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-ideal-image/tsconfig.client.json
+++ b/packages/docusaurus-plugin-ideal-image/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/theme", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-ideal-image/tsconfig.json
+++ b/packages/docusaurus-plugin-ideal-image/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-pwa/tsconfig.client.json
+++ b/packages/docusaurus-plugin-pwa/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
    "rootDir": "src",
    "outDir": "lib",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext"
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": [
    "src/theme/",
--- a/packages/docusaurus-plugin-pwa/tsconfig.json
+++ b/packages/docusaurus-plugin-pwa/tsconfig.json
@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [
    {"path": "./tsconfig.client.json"},
    {"path": "./tsconfig.worker.json"}
@ -7,7 +7,7 @@
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-pwa/tsconfig.worker.json
+++ b/packages/docusaurus-plugin-pwa/tsconfig.worker.json
@ -1,11 +1,11 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "composite": true,
    "incremental": true,
    "lib": ["webworker", "esnext"],
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-worker",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-worker",
    "rootDir": "src",
    "outDir": "lib",
    "moduleResolution": "bundler",
--- a/packages/docusaurus-plugin-sitemap/tsconfig.json
+++ b/packages/docusaurus-plugin-sitemap/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-plugin-vercel-analytics/tsconfig.client.json
+++ b/packages/docusaurus-plugin-vercel-analytics/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/analytics.ts", "src/options.ts", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-plugin-vercel-analytics/tsconfig.json
+++ b/packages/docusaurus-plugin-vercel-analytics/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-preset-classic/tsconfig.json
+++ b/packages/docusaurus-preset-classic/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-remark-plugin-npm2yarn/tsconfig.json
+++ b/packages/docusaurus-remark-plugin-npm2yarn/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus-theme-classic/src/theme/Navbar/Search/styles.module.css
+++ b/packages/docusaurus-theme-classic/src/theme/Navbar/Search/styles.module.css
@ -9,15 +9,8 @@
 Workaround to avoid rendering empty search container
 See https://github.com/facebook/docusaurus/pull/9385
 */
-/*
-TODO temporary @supports check, remove before 2025
-only needed for Firefox < 121
-see https://github.com/facebook/docusaurus/issues/9527#issuecomment-1805272379
- */
-@supports selector(:has(*)) {
-  .navbarSearchContainer:not(:has(> *)) {
-    display: none;
-  }
+.navbarSearchContainer:empty {
+  display: none;
 }

@media (max-width: 996px) {
--- a/packages/docusaurus-theme-classic/tsconfig.client.json
+++ b/packages/docusaurus-theme-classic/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
    "rootDir": "src",
    "outDir": "lib",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext"
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": [
    "src/nprogress.ts",
--- a/packages/docusaurus-theme-classic/tsconfig.json
+++ b/packages/docusaurus-theme-classic/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-theme-common/tsconfig.json
+++ b/packages/docusaurus-theme-common/tsconfig.json
@ -1,16 +1,11 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
-    "sourceMap": true,
-    "declarationMap": true,
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client",
+    "sourceMap": true,
+    "declarationMap": true
  },
  "include": ["src"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-theme-live-codeblock/tsconfig.client.json
+++ b/packages/docusaurus-theme-live-codeblock/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
    "rootDir": "src",
    "outDir": "lib",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext"
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/theme", "src/*.d.ts", "src/custom-buble.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-theme-live-codeblock/tsconfig.json
+++ b/packages/docusaurus-theme-live-codeblock/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-theme-mermaid/tsconfig.client.json
+++ b/packages/docusaurus-theme-mermaid/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
    "rootDir": "src",
    "outDir": "lib",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext"
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/client", "src/theme", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-theme-mermaid/tsconfig.json
+++ b/packages/docusaurus-theme-mermaid/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts
+++ b/packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts
@ -21,6 +21,7 @@ declare module '@docusaurus/theme-search-algolia' {
        from: string;
        to: string;
      };
+      insights?: boolean;
    };
  };
  export type UserThemeConfig = DeepPartial<ThemeConfig>;
--- a/packages/docusaurus-theme-search-algolia/tsconfig.client.json
+++ b/packages/docusaurus-theme-search-algolia/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
    "rootDir": "src",
    "outDir": "lib",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext"
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/theme", "src/client", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus-theme-search-algolia/tsconfig.json
+++ b/packages/docusaurus-theme-search-algolia/tsconfig.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.client.json"}],
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/docusaurus-theme-translations/locales/it/theme-common.json
+++ b/packages/docusaurus-theme-translations/locales/it/theme-common.json
@ -18,7 +18,7 @@
  "theme.admonition.danger": "pericolo",
  "theme.admonition.info": "informazioni",
  "theme.admonition.note": "note",
-  "theme.admonition.tip": "mancia",
+  "theme.admonition.tip": "suggerimento",
  "theme.admonition.warning": "warning",
  "theme.blog.archive.description": "Archivio",
  "theme.blog.archive.title": "Archivio",
--- a/packages/docusaurus-theme-translations/tsconfig.build.json
+++ b/packages/docusaurus-theme-translations/tsconfig.build.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "composite": true,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus-theme-translations/tsconfig.json
+++ b/packages/docusaurus-theme-translations/tsconfig.json
@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [{"path": "./tsconfig.build.json"}],
  "compilerOptions": {
    "noEmit": true,
--- a/packages/docusaurus-utils-common/tsconfig.json
+++ b/packages/docusaurus-utils-common/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus-utils-validation/tsconfig.json
+++ b/packages/docusaurus-utils-validation/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus-utils/tsconfig.json
+++ b/packages/docusaurus-utils/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "sourceMap": true,
    "declarationMap": true,
    "rootDir": "src",
--- a/packages/docusaurus/bin/docusaurus.mjs
+++ b/packages/docusaurus/bin/docusaurus.mjs
@ -115,6 +115,10 @@ cli
    '--skip-build',
    'skip building website before deploy it (default: false)',
  )
+  .option(
+    '--target-dir <dir>',
+    'path to the target directory to deploy to (default: `.`)',
+  )
  .action(deploy);

 /**
--- a/packages/docusaurus/src/client/App.tsx
+++ b/packages/docusaurus/src/client/App.tsx
@ -25,9 +25,19 @@ import SiteMetadataDefaults from './SiteMetadataDefaults';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
 import HasHydratedDataAttribute from './hasHydratedDataAttribute';

-export default function App(): JSX.Element {
-  const routeElement = renderRoutes(routes);
+const routesElement = renderRoutes(routes);
+
+function AppNavigation() {
  const location = useLocation();
+  const normalizedLocation = normalizeLocation(location);
+  return (
+    <PendingNavigation location={normalizedLocation}>
+      {routesElement}
+    </PendingNavigation>
+  );
+}
+
+export default function App(): JSX.Element {
  return (
    <ErrorBoundary>
      <DocusaurusContextProvider>
@ -36,9 +46,7 @@ export default function App(): JSX.Element {
            <SiteMetadataDefaults />
            <SiteMetadata />
            <BaseUrlIssueBanner />
-            <PendingNavigation location={normalizeLocation(location)}>
-              {routeElement}
-            </PendingNavigation>
+            <AppNavigation />
          </Root>
          <HasHydratedDataAttribute />
        </BrowserContextProvider>
--- a/packages/docusaurus/src/commands/deploy.ts
+++ b/packages/docusaurus/src/commands/deploy.ts
@ -19,6 +19,7 @@ export type DeployCLIOptions = Pick<
  'config' | 'locale' | 'outDir'
 > & {
  skipBuild?: boolean;
+  targetDir?: string;
 };

 // GIT_PASS env variable should not appear in logs
@ -185,32 +186,33 @@ You can also set the deploymentBranch property in docusaurus.config.js .`);
  const currentCommit = shellExecLog('git rev-parse HEAD').stdout.trim();

  const runDeploy = async (outputDirectory: string) => {
+    const targetDirectory = cliOptions.targetDir ?? '.';
    const fromPath = outputDirectory;
    const toPath = await fs.mkdtemp(
      path.join(os.tmpdir(), `${projectName}-${deploymentBranch}`),
    );
    shell.cd(toPath);

-    // Check out deployment branch when cloning repository, and then remove all
-    // the files in the directory. If the 'clone' command fails, assume that
-    // the deployment branch doesn't exist, and initialize git in an empty
-    // directory, check out a clean deployment branch and add remote.
+    // Clones the repo into the temp folder and checks out the target branch.
+    // If the branch doesn't exist, it creates a new one based on the
+    // repository default branch.
    if (
      shellExecLog(
        `git clone --depth 1 --branch ${deploymentBranch} ${deploymentRepoURL} "${toPath}"`,
-      ).code === 0
+      ).code !== 0
    ) {
-      shellExecLog('git rm -rf .');
-    } else {
-      shellExecLog('git init');
+      shellExecLog(`git clone --depth 1 ${deploymentRepoURL} "${toPath}"`);
      shellExecLog(`git checkout -b ${deploymentBranch}`);
-      shellExecLog(`git remote add origin ${deploymentRepoURL}`);
    }

+    // Clear out any existing contents in the target directory
+    shellExecLog(`git rm -rf ${targetDirectory}`);
+
+    const targetPath = path.join(toPath, targetDirectory);
    try {
-      await fs.copy(fromPath, toPath);
+      await fs.copy(fromPath, targetPath);
    } catch (err) {
-      logger.error`Copying build assets from path=${fromPath} to path=${toPath} failed.`;
+      logger.error`Copying build assets from path=${fromPath} to path=${targetPath} failed.`;
      throw err;
    }
    shellExecLog('git add --all');
@ -254,7 +256,8 @@ You can also set the deploymentBranch property in docusaurus.config.js .`);
  if (!cliOptions.skipBuild) {
    // Build site, then push to deploymentBranch branch of specified repo.
    try {
-      await build(siteDir, cliOptions, false).then(() => runDeploy(outDir));
+      await build(siteDir, cliOptions, false);
+      await runDeploy(outDir);
    } catch (err) {
      logger.error('Deployment of the build output failed.');
      throw err;
--- a/packages/docusaurus/src/server/plugins/tests/routeConfig.test.ts
+++ b/packages/docusaurus/src/server/plugins/tests/routeConfig.test.ts
@ -202,9 +202,7 @@ describe('sortRoutes', () => {
      },
    ];

-    sortRoutes(routes);
-
-    expect(routes).toMatchSnapshot();
+    expect(sortRoutes(routes, '/')).toMatchSnapshot();
  });

  it('sorts route config recursively', () => {
@ -248,9 +246,7 @@ describe('sortRoutes', () => {
      },
    ];

-    sortRoutes(routes);
-
-    expect(routes).toMatchSnapshot();
+    expect(sortRoutes(routes, '/')).toMatchSnapshot();
  });

  it('sorts route config given a baseURL', () => {
@ -290,8 +286,27 @@ describe('sortRoutes', () => {
      },
    ];

-    sortRoutes(routes, baseURL);
+    expect(sortRoutes(routes, baseURL)).toMatchSnapshot();
+  });

-    expect(routes).toMatchSnapshot();
+  it('sorts parent route configs when one included in another', () => {
+    const r1: RouteConfig = {
+      path: '/one',
+      component: '',
+      routes: [{path: `/one/myDoc`, component: ''}],
+    };
+    const r2: RouteConfig = {
+      path: '/',
+      component: '',
+      routes: [{path: `/someDoc`, component: ''}],
+    };
+    const r3: RouteConfig = {
+      path: '/one/another',
+      component: '',
+      routes: [{path: `/one/another/myDoc`, component: ''}],
+    };
+
+    expect(sortRoutes([r1, r2, r3], '/')).toEqual([r3, r1, r2]);
+    expect(sortRoutes([r3, r1, r2], '/')).toEqual([r3, r1, r2]);
  });
 });
--- a/packages/docusaurus/src/server/plugins/plugins.ts
+++ b/packages/docusaurus/src/server/plugins/plugins.ts
@ -224,17 +224,18 @@ async function executeAllPluginsAllContentLoaded({
 // - contentLoaded()
 // - allContentLoaded()
 function mergeResults({
+  baseUrl,
  plugins,
  allContentLoadedResult,
 }: {
+  baseUrl: string;
  plugins: LoadedPlugin[];
  allContentLoadedResult: AllContentLoadedResult;
 }) {
-  const routes: PluginRouteConfig[] = [
-    ...aggregateRoutes(plugins),
-    ...allContentLoadedResult.routes,
-  ];
-  sortRoutes(routes);
+  const routes: PluginRouteConfig[] = sortRoutes(
+    [...aggregateRoutes(plugins), ...allContentLoadedResult.routes],
+    baseUrl,
+  );

  const globalData: GlobalData = mergeGlobalData(
    aggregateGlobalData(plugins),
@ -279,6 +280,7 @@ export async function loadPlugins(
    });

    const {routes, globalData} = mergeResults({
+      baseUrl: context.baseUrl,
      plugins,
      allContentLoadedResult,
    });
@ -324,6 +326,7 @@ export async function reloadPlugin({
      });

      const {routes, globalData} = mergeResults({
+        baseUrl: context.baseUrl,
        plugins,
        allContentLoadedResult,
      });
--- a/packages/docusaurus/src/server/plugins/routeConfig.ts
+++ b/packages/docusaurus/src/server/plugins/routeConfig.ts
@ -27,10 +27,11 @@ export function applyRouteTrailingSlash<Route extends RouteConfig>(
  };
 }

-export function sortRoutes(
-  routeConfigs: RouteConfig[],
-  baseUrl: string = '/',
-): void {
+export function sortRoutes<Route extends RouteConfig>(
+  routesToSort: Route[],
+  baseUrl: string,
+): Route[] {
+  const routeConfigs = [...routesToSort];
  // Sort the route config. This ensures that route with nested
  // routes is always placed last.
  routeConfigs.sort((a, b) => {
@ -48,6 +49,23 @@ export function sortRoutes(
    if (!a.routes && b.routes) {
      return -1;
    }
+
+    // If both are parent routes (for example routeBasePath: "/" and "/docs/"
+    // We must order them carefully in case of overlapping paths
+    if (a.routes && b.routes) {
+      if (a.path === b.path) {
+        // We don't really support that kind of routing ATM
+        // React-Router by default will only "enter" a single parent route
+      } else {
+        if (a.path.includes(b.path)) {
+          return -1;
+        }
+        if (b.path.includes(a.path)) {
+          return 1;
+        }
+      }
+    }
+
    // Higher priority get placed first.
    if (a.priority || b.priority) {
      const priorityA = a.priority ?? 0;
@ -64,7 +82,9 @@ export function sortRoutes(

  routeConfigs.forEach((routeConfig) => {
    if (routeConfig.routes) {
-      sortRoutes(routeConfig.routes, baseUrl);
+      routeConfig.routes = sortRoutes(routeConfig.routes, baseUrl);
    }
  });
+
+  return routeConfigs;
 }
--- a/packages/docusaurus/tsconfig.client.json
+++ b/packages/docusaurus/tsconfig.client.json
@ -1,15 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.client.json",
  "compilerOptions": {
-    "noEmit": false,
-    "composite": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
-    "moduleResolution": "bundler",
-    "module": "esnext",
-    "target": "esnext",
    "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
  },
  "include": ["src/client", "src/*.d.ts"],
  "exclude": ["**/__tests__/**"]
--- a/packages/docusaurus/tsconfig.json
+++ b/packages/docusaurus/tsconfig.json
@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "references": [
    {"path": "./tsconfig.server.json"},
    {"path": "./tsconfig.client.json"}
--- a/packages/docusaurus/tsconfig.server.json
+++ b/packages/docusaurus/tsconfig.server.json
@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "composite": true,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/eslint-plugin/tsconfig.json
+++ b/packages/eslint-plugin/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/lqip-loader/tsconfig.json
+++ b/packages/lqip-loader/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/packages/stylelint-copyright/tsconfig.json
+++ b/packages/stylelint-copyright/tsconfig.json
@ -1,9 +1,9 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
    "rootDir": "src",
    "outDir": "lib"
  },
--- a/project-words.txt
+++ b/project-words.txt
@ -12,18 +12,10 @@ Alexey
 algoliasearch
 alignof
 Allez
-analyse
-Ancheta
-ancheta
-Ancheta's
-Anshul
 anshul
-apexfp
-APFS
+Anshul
 apfs
-APISIX
-apisix
-Appcircle
+APFS
 appinstalled
 Applanga
 architecting
@ -36,8 +28,8 @@ Atto
 attobot
 Autoconverted
 autofix
-Autogen
 autogen
+Autogen
 autogenerating
 autohide
 Autolinks
@ -52,12 +44,8 @@ Batect
 bedly
 beforeinstallprompt
 Bhatt
-blinkshell
-Blockquotes
 blockquotes
-Blogasaurus
-blogasaurus
-blogmatheusbrunelli
+Blockquotes
 Bokmål
 Botonic
 botonic
@ -67,9 +55,8 @@ Brainboard
 brainboard
 Brobot
 browserstack
-Brunelli
-Buble
 buble
+Buble
 Buble's
 bunx
 caabernathy
@ -81,20 +68,14 @@ Candillon
 carreira
 cdabcdab
 cdpath
-Cena
 cena
+Cena
 changefreq
-Chatbots
-chatkitty
-Chedeau
 chedeau
-Cho's
-CIPP
-claritychallenge
+Chedeau
 Clément
-Codegen
 codegen
-codehooks
+Codegen
 codesandbox
 Codespaces
 codesweetly
@ -112,20 +93,16 @@ creativecommons
 cryptodevhub
 Csapo
 Csvg
-Customizability
 customizability
-Dabit
+Customizability
 dabit
+Dabit
 Daishi
-Darklang
-darklang
-Datagit
 datagit
+Datagit
 Datagit's
 dedup
-Desenvolvimento
-Devresse
-devspace
+Déja
 devto
 dicas
 difranca
@ -138,47 +115,32 @@ djamaile
 Dmitry
 Docasaurus
 docsearch
+Docsearch
 Docsify
-Docu
 docu
+Docu
 docusuarus
 Docz
-Dogfood
 dogfood
-Dogfooding
+Dogfood
 dogfooding
+Dogfooding
 Dojocat
-draftjs
-Duolingo
-Dynamoose
-Dyte
 dyte
-Déja
-Easyjwt
-easyjwt
+Dyte
 easyops
-Easypanel
-easypanel
-ediscovery
-edulinks
-Eightshift
-eightshift
-Enarx
-enarx
-Endi
 endi
-Endi's
-Endilie
+Endi
 endilie
+Endilie
 endiliey
+Endi's
 ERRNAMETOOLONG
 Erxes
 erxes
 evaluable
-evantay
-evershop
-Execa
 execa
+Execa
 externalwaiting
 Extracranial
 failfast
@ -219,49 +181,38 @@ Goss
 Gotenberg
 gotenberg
 Goyal
-Gtag
 gtag
-GTFS
-gtfs
+Gtag
 hahaha
 Hamel
-Hanabi
-Haochen
-haochen
-Harmonoid
-Hashnode
-hashnode
-Hasura
 hasura
-hcaptcha
+Hasura
 Heavener
-Hideable
+Héctor
+héllô
 hideable
+Hideable
 hola
 Homarr
 Hostman
 hoverable
 httpin
 Husain
-Héctor
-héllô
-iammassoud
 IANAD
 icodex
 idempotency
 Iframes
 Immer
-inexistant
-Infima
 infima
+Infima
 Infima's
 inlines
 intelagent
 Intelli
 intellij
 interactiveness
-Interpolatable
 interpolatable
+Interpolatable
 Investec
 javadoc
 Jellus
@ -279,17 +230,11 @@ Junjie
 junjie
 Kanekotic's
 Kaszubowski
-Katex
 katex
+Katex
 Kato
-Kaustubh
-kaustubhk
-Kaya
-Keebio
-Keytar
 keytar
-Khyron
-khyron
+Keytar
 Kinsta
 Kishan
 Knapen
@ -308,25 +253,18 @@ Kuizuo's
 kwatch
 labviewbook
 Lamana
-Lastmod
 lastmod
-Leedom
-leedom
-Lifecycles
+Lastmod
 lifecycles
-Linkify
+Lifecycles
 linkify
-Liqvid
-liqvid
-livekit
-livros
+Linkify
 Localizable
 lockb
 Lorber
 Lorber's
-LQIP
 lqip
-lsfusion
+LQIP
 lunrjs
 Maboudi
 Mailgo
@ -335,32 +273,24 @@ Mapillary
 mapillaryjs
 Marcey
 Marcey's
-Markprompt
 markprompt
+Markprompt
 Massoud
 Matej
 Matheus
 mathjax
 maxlynch
 maxresdefault
-MDAST
 mdast
+MDAST
 mdwn
 MDXA
 MDXAST
 MDXHAST
-Mdxjs
 mdxjs
-mediamachine
-Meilisearch
+Mdxjs
 meilisearch
-Meli
-meli
-Memgraph
-memgraph
-mentees
-Meoo
-meoo
+Meilisearch
 merveilleuse
 metadatum
 Metalyoung
@ -368,25 +298,15 @@ metalyoung
 metastring
 metrica
 Metrika
-microcontrollers
-Microdata
 microdata
-Mikro
-mikro
-Mindmap
+Microdata
 mindmap
-mintmetrics
-Mixcore
-mixcore
+Mindmap
 mkdn
 mkdocs
 mkdown
-Modrinth
-Moesif
 moesif
-moja
-mojaglobal
-Moodle
+Moesif
 msapplication
 muito
 multiplatform
@ -395,10 +315,8 @@ Mäsiar
 Nabors
 Nakagawa
 nand
-Nango
-nanos
-Navigations
 navigations
+Navigations
 navlink
 nbdoc
 netboot
@ -427,32 +345,28 @@ novu
 npmjs
 nprogress
 Nuxt
-OHIP
-Omic
+ödingers
 opensearch
 opensearchdescription
 opensource
 optimisation
 optimizt
-Orama
 orama
-orbitjs
-Orta
+Orama
 orta
-ossinsight
-Outerbounds
+Orta
+O’Shannessy
 outerbounds
+Outerbounds
 overrideable
 ozaki
-ozakione
-O’Shannessy
 pageview
-Palenight
 palenight
+Palenight
 Paletton
 Palo
-Paraiso
 paraiso
+Paraiso
 pathinfo
 Patrik
 patrikmasiar
@ -468,23 +382,22 @@ peradaban
 Pglet
 pglet
 philpl
-Photoshop
 photoshop
+Photoshop
 picomatch
 pincman
 pincman's
 Pipeable
 playbtn
-Pluggable
 pluggable
-Plushie
+Pluggable
 plushie
+Plushie
 plushies
 Polkadot
 posthog
-pptxgenjs
-Precache
 precache
+Precache
 precached
 precaching
 preconfigured
@ -496,8 +409,8 @@ printfn
 println
 prismjs
 producthunt
-Profilo
 profilo
+Profilo
 Protobuf
 protobuffet
 PRPL
@ -509,8 +422,8 @@ quantcdn
 quasis
 Quddus
 Quddús
-Quickwit
 quickwit
+Quickwit
 rachelnabors
 Rahamat
 Rainbond
@ -528,25 +441,18 @@ Redoc
 redocusaurus
 redwoodjs
 refactorings
-Regx
-regx
-Rehype
 rehype
-Reloadable
+Rehype
 reloadable
-Remirror
-remirror
+Reloadable
 renderable
 repeaterjs
 replicad
 REPONAME
-Resoto
-Retrocompatibility
 retrocompatibility
-Retrocompatible
+Retrocompatibility
 retrocompatible
-Rivalis
-rivalis
+Retrocompatible
 rmiz
 rnrh
 Rokt
@ -564,20 +470,17 @@ saleor
 sapcloudsdk
 saurus
 Scaleway
-sciwp
-Seaography
-Sebastien
 sebastien
+Sebastien
+Sébastien
 sebastienlorber
 sensical
 serialport
 setaf
 setext
 setlocal
-Shabad
-shabados
-Shiki
 shiki
+Shiki
 shortcodes
 Shotstack
 shotstack
@ -591,15 +494,8 @@ slorber
 sluggified
 sluggifies
 sluggify
-smartcookieweb
-smashgg
-sodaforsparc
-Solana
 solana
-someengineering
-Spicetify
-spicetify
-spotifyapi
+Solana
 spâce
 sqlframes
 stackblitz
@ -623,29 +519,16 @@ subsetting
 subsubcategory
 subsubfolder
 subsubsection
-Subsubsubfolder
 subsubsubfolder
+Subsubsubfolder
 Sucipto
 Sunghyun
 sunsetting
-Supabase
 supabase
-SVGR
+Supabase
 svgr
-Svix
-svix
-sweetcode
+SVGR
 swizzlable
-synergyzing
-Sébastien
-Takken
-talentbrick
-Tamal
-tamalwebsite
-Tasit
-tasit
-techharvesting
-technotes
 Teik
 templating
 Thanos
@ -660,31 +543,26 @@ toolsets
 toplevel
 Transifex
 transpiles
-Treeified
 treeified
+Treeified
 treeifies
 treeify
-Triaging
 triaging
-TRPG
-trpgengine
-TSEI
+Triaging
 TSES
 Tuist
 tuist
 twoslash
 typecheck
 typesafe
-Typesense
 typesense
+Typesense
 Unavatar
 unlinkable
-Unlisteds
 unlisteds
-Unlocalized
+Unlisteds
 unlocalized
-Unmand
-unmand
+Unlocalized
 unnormalized
 unswizzle
 upvotes
@ -692,10 +570,8 @@ urlset
 Vannicatte
 Vantevo
 vbnet
-Verida
-verida
-Vetter
 vetter
+Vetter
 vfile
 Vicenti
 Vieira
@ -705,13 +581,8 @@ Vishal
 vjeux
 voir
 waivable
-Warung
-wate
-Wate's
-WCAG
 wcag
-Webber's
-webdriverio
+WCAG
 webfactory
 Webiny
 webiny
@ -724,8 +595,8 @@ Xiaohai's
 Xplorer
 XSOAR
 Yacop
-Yangshun
 yangshun
+Yangshun
 yangshunz
 Yeecord
 yeecord
@ -735,5 +606,3 @@ zoomable
 Zowe
 zowe
 zpao
-zxuqian
-ödingers
--- a/tsconfig.base.client.json
+++ b/tsconfig.base.client.json
@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "composite": true,
+    "incremental": true,
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "target": "esnext"
+  }
+}
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
--- a/website/docs/cli.mdx
+++ b/website/docs/cli.mdx
@ -144,6 +144,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the
 | `--locale` |  | Deploy the site in the specified locale. If not specified, all known locales are deployed. |
 | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
 | `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. |
+| `--target-dir` | `.` | Path to the target directory to deploy to. |
 | `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |

 ### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
--- a/website/docs/migration/index.mdx
+++ b/website/docs/migration/index.mdx
@ -11,3 +11,42 @@ Docusaurus versioning is based on the `major.minor.patch` scheme and respects [*
 import DocCardList from '@theme/DocCardList';

 <DocCardList />
+
+## Troubleshooting upgrades
+
+When upgrading Docusaurus you may experience issues caused by mismatching cached dependencies - there are a few troubleshooting steps you should perform to resolve these common issues before reporting a bug or seeking support.
+
+### Run the `clear` command
+
+This CLI command is used to clear a Docusaurus site's generated assets, caches and build artifacts.
+
+```bash npm2yarn
+npm run clear
+```
+
+### Remove `node_modules` and your lock file(s)
+
+Remove the `node_modules` folder and your package manager's lock file using the following:
+
+<Tabs>
+<TabItem label="Bash" value="bash">
+
+```bash
+rm -rf node_modules yarn.lock package-lock.json
+```
+
+</TabItem>
+<TabItem label="PowerShell" value="powershell">
+
+```powershell
+@('node_modules','yarn.lock','package-lock.json') | Remove-Item -Force -Recurse -ErrorAction SilentlyContinue
+```
+
+</TabItem>
+</Tabs>
+
+Then reinstall packages and regenerate the `lock` file using:
+
+```bash npm2yarn
+npm install
+```
--- a/website/docs/migration/v3.mdx
+++ b/website/docs/migration/v3.mdx
@ -36,7 +36,7 @@ Docusaurus v3 now uses the following dependencies:
 - Node.js v18.0+
 - React v18.0+
 - MDX v3.0+
- TypeScript v5.0+
+- TypeScript v5.1+
 - prism-react-renderer v2.0+
 - react-live v4.0+
 - remark-emoji v4.0+
@ -98,7 +98,7 @@ For TypeScript users:
     // upgrade React types to v18.0+
 -    "@types/react": "^17.0.69",
 +    "@types/react": "^18.2.29",
-     // upgrade TypeScript to v5.0+
+     // upgrade TypeScript to v5.1+
 -    "typescript": "~4.7.4"
 +    "typescript": "~5.2.2"
   }
@ -689,9 +689,9 @@ However, this is a new major library version containing breaking changes, and we

 :::

-### TypeScript v5.0+
+### TypeScript v5.1+

-Docusaurus v3 now requires **TypeScript >= 5.0**.
+Docusaurus v3 now requires **TypeScript >= 5.1**.

 :::info How to upgrade

--- a/website/docs/search.mdx
+++ b/website/docs/search.mdx
@ -47,9 +47,17 @@ You can read more about migration from the legacy DocSearch infra in [our blog p

 After your application has been approved and deployed, you will receive an email with all the details for you to add DocSearch to your project. Editing and managing your crawls can be done via [the web interface](https://crawler.algolia.com/). Indices are readily available after deployment, so manual configuration usually isn't necessary.

-:::tip
+:::danger Use the recommended crawler config

-It is highly recommended to use a config similar to the [**Docusaurus v3 website config**](https://docsearch.algolia.com/docs/templates/#docusaurus-v2-template).
+It is highly recommended to use our official [**Docusaurus v3 crawler configuration**](https://docsearch.algolia.com/docs/templates/#docusaurus-v3-template). We cannot support you if you choose a different crawler configuration.
+
+:::
+
+:::warning When updating your crawler config
+
+The crawler configuration contains a `initialIndexSettings`, which will only be used to initialize your Algolia index if it does not exist yet.
+
+If you update your `initialIndexSettings` crawler setting, it is possible to update the index manually through the interface, but [the Algolia team recommends to delete your index and then restart a crawl](https://github.com/facebook/docusaurus/issues/9200#issuecomment-1667338492) to fully reinitialize it with the new settings.

 :::

@ -116,6 +124,9 @@ export default {
      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      insights: false,
+
      //... other Algolia params
    },
    // highlight-end
@ -197,6 +208,12 @@ Refer to the relevant [Algolia faceting documentation](https://www.algolia.com/d

 :::

+:::warning Contextual search doesn't work?
+
+If you only get search results when Contextual Search is disabled, this is very likely because of an [index configuration issue](#algolia-no-search-results).
+
+:::
+
 ### Styling your Algolia search {#styling-your-algolia-search}

 By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.
@ -272,6 +289,53 @@ If you prefer to edit the Algolia search React component, [swizzle](swizzling.md
 npm run swizzle @docusaurus/theme-search-algolia SearchBar
 ```

+### Troubleshooting {#algolia-troubleshooting}
+
+Here are the most common issues Docusaurus users face when using Algolia DocSearch.
+
+#### No Search Results {#algolia-no-search-results}
+
+Seeing no search results is usually related to an **index configuration problem**.
+
+<details>
+  <summary>How to check if I have an config problem?</summary>
+
+Docusaurus uses [Algolia faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/) for its [Contextual Search](#contextual-search) feature, to create dynamic queries such as:
+
+```json
+[
+  "language:en",
+  [
+    "docusaurus_tag:default",
+    "docusaurus_tag:docs-default-3.2.1",
+    "docusaurus_tag:docs-community-current",
+    "docusaurus_tag:docs-docs-tests-current"
+  ]
+]
+```
+
+On the Algolia UI, your index should allow to create facet queries on fields `docusaurus_tag`, `language`, `lang`, `version`, `type`, as shown in the screenshot below:
+
+![Algolia index showing appropriate faceting fields](/img/docsearch-troubleshoot-index-facets.jpg)
+
+Alternatively, if you disable [Contextual Search](#contextual-search) with `{contextualSearch: false}` (which we don't particularly recommend), Docusaurus will not use facet queries, and you should start seeing results.
+
+</details>
+
+:::danger Use the recommended configuration
+
+We [recommend a specific crawler configuration](#algolia-index-configuration) for a good reason. We cannot support you if you choose to use a different configuration.
+
+:::
+
+You can fix index configuration problems by following those steps:
+
+1. Use the [recommend crawler configuration](#algolia-index-configuration)
+2. Delete your index through the UI
+3. Trigger a new crawl through the UI
+4. Check your index is recreated with the appropriate faceting fields: `docusaurus_tag`, `language`, `lang`, `version`, `type`
+5. See that you now get search results, even with [Contextual Search](#contextual-search) enabled
+
 ### Support {#algolia-support}

 The Algolia DocSearch team can help you figure out search problems on your site.
--- a/website/docs/typescript-support.mdx
+++ b/website/docs/typescript-support.mdx
@ -6,7 +6,7 @@ description: Docusaurus is written in TypeScript and provides first-class TypeSc

 Docusaurus is written in TypeScript and provides first-class TypeScript support.

-The minimum required version is **TypeScript 5.0**.
+The minimum required version is **TypeScript 5.1**.

 ## Initialization {#initialization}

--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@ -5,7 +5,6 @@
 * LICENSE file in the root directory of this source tree.
 */
 import path from 'path';
-
 import npm2yarn from '@docusaurus/remark-plugin-npm2yarn';
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
@ -529,6 +528,7 @@ export default async function createConfigAsync() {
          'haskell',
          'matlab',
          'PHp',
+          'powershell',
          'bash',
          'diff',
          'json',
--- a/website/static/img/docsearch-troubleshoot-index-facets.jpg
+++ b/website/static/img/docsearch-troubleshoot-index-facets.jpg
--- a/website/static/manifest.json
+++ b/website/static/manifest.json
@ -1,5 +1,5 @@
 {
-  "name": "Docusaurus v2",
+  "name": "Docusaurus",
  "short_name": "Docusaurus",
  "theme_color": "#2196f3",
  "background_color": "#424242",
--- a/website/versioned_docs/version-2.x/search.mdx
+++ b/website/versioned_docs/version-2.x/search.mdx
@ -116,6 +116,9 @@ module.exports = {
      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      insights: false,
+
      //... other Algolia params
    },
    // highlight-end
--- a/website/versioned_docs/version-3.0.1/migration/v3.mdx
+++ b/website/versioned_docs/version-3.0.1/migration/v3.mdx
@ -36,7 +36,7 @@ Docusaurus v3 now uses the following dependencies:
 - Node.js v18.0+
 - React v18.0+
 - MDX v3.0+
- TypeScript v5.0+
+- TypeScript v5.1+
 - prism-react-renderer v2.0+
 - react-live v4.0+
 - remark-emoji v4.0+
@ -98,7 +98,7 @@ For TypeScript users:
     // upgrade React types to v18.0+
 -    "@types/react": "^17.0.69",
 +    "@types/react": "^18.2.29",
-     // upgrade TypeScript to v5.0+
+     // upgrade TypeScript to v5.1+
 -    "typescript": "~4.7.4"
 +    "typescript": "~5.2.2"
   }
@ -601,9 +601,9 @@ However, this is a new major library version containing breaking changes, and we

 :::

-### TypeScript v5.0+
+### TypeScript v5.1+

-Docusaurus v3 now requires **TypeScript >= 5.0**.
+Docusaurus v3 now requires **TypeScript >= 5.1**.

 :::info How to upgrade

--- a/website/versioned_docs/version-3.0.1/search.mdx
+++ b/website/versioned_docs/version-3.0.1/search.mdx
@ -116,6 +116,9 @@ export default {
      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      insights: false,
+
      //... other Algolia params
    },
    // highlight-end
--- a/website/versioned_docs/version-3.0.1/typescript-support.mdx
+++ b/website/versioned_docs/version-3.0.1/typescript-support.mdx
@ -6,7 +6,7 @@ description: Docusaurus is written in TypeScript and provides first-class TypeSc

 Docusaurus is written in TypeScript and provides first-class TypeScript support.

-The minimum required version is **TypeScript 5.0**.
+The minimum required version is **TypeScript 5.1**.

 ## Initialization {#initialization}

--- a/website/versioned_docs/version-3.1.1/migration/v3.mdx
+++ b/website/versioned_docs/version-3.1.1/migration/v3.mdx
@ -36,7 +36,7 @@ Docusaurus v3 now uses the following dependencies:
 - Node.js v18.0+
 - React v18.0+
 - MDX v3.0+
- TypeScript v5.0+
+- TypeScript v5.1+
 - prism-react-renderer v2.0+
 - react-live v4.0+
 - remark-emoji v4.0+
@ -98,7 +98,7 @@ For TypeScript users:
     // upgrade React types to v18.0+
 -    "@types/react": "^17.0.69",
 +    "@types/react": "^18.2.29",
-     // upgrade TypeScript to v5.0+
+     // upgrade TypeScript to v5.1+
 -    "typescript": "~4.7.4"
 +    "typescript": "~5.2.2"
   }
@ -689,9 +689,9 @@ However, this is a new major library version containing breaking changes, and we

 :::

-### TypeScript v5.0+
+### TypeScript v5.1+

-Docusaurus v3 now requires **TypeScript >= 5.0**.
+Docusaurus v3 now requires **TypeScript >= 5.1**.

 :::info How to upgrade

--- a/website/versioned_docs/version-3.1.1/search.mdx
+++ b/website/versioned_docs/version-3.1.1/search.mdx
@ -116,6 +116,9 @@ export default {
      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      insights: false,
+
      //... other Algolia params
    },
    // highlight-end
--- a/website/versioned_docs/version-3.1.1/typescript-support.mdx
+++ b/website/versioned_docs/version-3.1.1/typescript-support.mdx
@ -6,7 +6,7 @@ description: Docusaurus is written in TypeScript and provides first-class TypeSc

 Docusaurus is written in TypeScript and provides first-class TypeScript support.

-The minimum required version is **TypeScript 5.0**.
+The minimum required version is **TypeScript 5.1**.

 ## Initialization {#initialization}

--- a/website/versioned_docs/version-3.2.1/migration/v3.mdx
+++ b/website/versioned_docs/version-3.2.1/migration/v3.mdx
@ -36,7 +36,7 @@ Docusaurus v3 now uses the following dependencies:
 - Node.js v18.0+
 - React v18.0+
 - MDX v3.0+
- TypeScript v5.0+
+- TypeScript v5.1+
 - prism-react-renderer v2.0+
 - react-live v4.0+
 - remark-emoji v4.0+
@ -98,7 +98,7 @@ For TypeScript users:
     // upgrade React types to v18.0+
 -    "@types/react": "^17.0.69",
 +    "@types/react": "^18.2.29",
-     // upgrade TypeScript to v5.0+
+     // upgrade TypeScript to v5.1+
 -    "typescript": "~4.7.4"
 +    "typescript": "~5.2.2"
   }
@ -689,9 +689,9 @@ However, this is a new major library version containing breaking changes, and we

 :::

-### TypeScript v5.0+
+### TypeScript v5.1+

-Docusaurus v3 now requires **TypeScript >= 5.0**.
+Docusaurus v3 now requires **TypeScript >= 5.1**.

 :::info How to upgrade

--- a/website/versioned_docs/version-3.2.1/search.mdx
+++ b/website/versioned_docs/version-3.2.1/search.mdx
@ -47,9 +47,17 @@ You can read more about migration from the legacy DocSearch infra in [our blog p

 After your application has been approved and deployed, you will receive an email with all the details for you to add DocSearch to your project. Editing and managing your crawls can be done via [the web interface](https://crawler.algolia.com/). Indices are readily available after deployment, so manual configuration usually isn't necessary.

-:::tip
+:::danger Use the recommended crawler config

-It is highly recommended to use a config similar to the [**Docusaurus v3 website config**](https://docsearch.algolia.com/docs/templates/#docusaurus-v2-template).
+It is highly recommended to use our official [**Docusaurus v3 crawler configuration**](https://docsearch.algolia.com/docs/templates/#docusaurus-v3-template). We cannot support you if you choose a different crawler configuration.
+
+:::
+
+:::warning When updating your crawler config
+
+The crawler configuration contains a `initialIndexSettings`, which will only be used to initialize your Algolia index if it does not exist yet.
+
+If you update your `initialIndexSettings` crawler setting, it is possible to update the index manually through the interface, but [the Algolia team recommends to delete your index and then restart a crawl](https://github.com/facebook/docusaurus/issues/9200#issuecomment-1667338492) to fully reinitialize it with the new settings.

 :::

@ -116,6 +124,9 @@ export default {
      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      insights: false,
+
      //... other Algolia params
    },
    // highlight-end
@ -197,6 +208,12 @@ Refer to the relevant [Algolia faceting documentation](https://www.algolia.com/d

 :::

+:::warning Contextual search doesn't work?
+
+If you only get search results when Contextual Search is disabled, this is very likely because of an [index configuration issue](#algolia-no-search-results).
+
+:::
+
 ### Styling your Algolia search {#styling-your-algolia-search}

 By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.
@ -272,6 +289,53 @@ If you prefer to edit the Algolia search React component, [swizzle](swizzling.md
 npm run swizzle @docusaurus/theme-search-algolia SearchBar
 ```

+### Troubleshooting {#algolia-troubleshooting}
+
+Here are the most common issues Docusaurus users face when using Algolia DocSearch.
+
+#### No Search Results {#algolia-no-search-results}
+
+Seeing no search results is usually related to an **index configuration problem**.
+
+<details>
+  <summary>How to check if I have an config problem?</summary>
+
+Docusaurus uses [Algolia faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/) for its [Contextual Search](#contextual-search) feature, to create dynamic queries such as:
+
+```json
+[
+  "language:en",
+  [
+    "docusaurus_tag:default",
+    "docusaurus_tag:docs-default-3.2.1",
+    "docusaurus_tag:docs-community-current",
+    "docusaurus_tag:docs-docs-tests-current"
+  ]
+]
+```
+
+On the Algolia UI, your index should allow to create facet queries on fields `docusaurus_tag`, `language`, `lang`, `version`, `type`, as shown in the screenshot below:
+
+![Algolia index showing appropriate faceting fields](/img/docsearch-troubleshoot-index-facets.jpg)
+
+Alternatively, if you disable [Contextual Search](#contextual-search) with `{contextualSearch: false}` (which we don't particularly recommend), Docusaurus will not use facet queries, and you should start seeing results.
+
+</details>
+
+:::danger Use the recommended configuration
+
+We [recommend a specific crawler configuration](#algolia-index-configuration) for a good reason. We cannot support you if you choose to use a different configuration.
+
+:::
+
+You can fix index configuration problems by following those steps:
+
+1. Use the [recommend crawler configuration](#algolia-index-configuration)
+2. Delete your index through the UI
+3. Trigger a new crawl through the UI
+4. Check your index is recreated with the appropriate faceting fields: `docusaurus_tag`, `language`, `lang`, `version`, `type`
+5. See that you now get search results, even with [Contextual Search](#contextual-search) enabled
+
 ### Support {#algolia-support}

 The Algolia DocSearch team can help you figure out search problems on your site.
--- a/website/versioned_docs/version-3.2.1/typescript-support.mdx
+++ b/website/versioned_docs/version-3.2.1/typescript-support.mdx
@ -6,7 +6,7 @@ description: Docusaurus is written in TypeScript and provides first-class TypeSc

 Docusaurus is written in TypeScript and provides first-class TypeScript support.

-The minimum required version is **TypeScript 5.0**.
+The minimum required version is **TypeScript 5.1**.

 ## Initialization {#initialization}