From 6b78ffd9133528c41d377bc2bee6a30c79d1b7ef Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 14:34:26 +0100
Subject: [PATCH 1/7] site custom CSS must be inserted at the end

---
 website/testCSSOrder.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/testCSSOrder.js b/website/testCSSOrder.js
index 6acee5b7f1d5..72e74e36563d 100644
--- a/website/testCSSOrder.js
+++ b/website/testCSSOrder.js
@@ -42,10 +42,10 @@ const EXPECTED_CSS_MARKERS = [
   '.tabs__item',
 
   // Test markers
-  '.test-marker-site-custom-css-unique-rule',
   '.test-marker-site-client-module',
   '.test-marker-theme-layout',
   '.test-marker-site-index-page',
+  '.test-marker-site-custom-css-unique-rule',
 
   // lazy loaded lib
   '.DocSearch-Modal',

From bb2aa5a71429b2464c37c24cedb778feae66ae9a Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 15:29:59 +0100
Subject: [PATCH 2/7] deprecate themeOptions.customCss

---
 .../src/__tests__/validateThemeConfig.test.js | 33 ++-----------
 .../docusaurus-theme-classic/src/index.ts     |  1 +
 .../docusaurus-theme-classic/src/options.ts   | 49 +++++++++++++++++++
 .../src/theme-classic.d.ts                    |  2 +-
 .../src/validateThemeConfig.ts                | 12 +++--
 packages/docusaurus-types/src/index.d.ts      |  1 +
 6 files changed, 62 insertions(+), 36 deletions(-)
 create mode 100644 packages/docusaurus-theme-classic/src/options.ts

diff --git a/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js b/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js
index e987f2ac6935..ee77185e99c6 100644
--- a/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js
+++ b/packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js
@@ -20,15 +20,6 @@ function testValidateThemeConfig(partialThemeConfig) {
   });
 }
 
-function testOk(partialThemeConfig) {
-  expect(
-    testValidateThemeConfig({...DEFAULT_CONFIG, ...partialThemeConfig}),
-  ).toEqual({
-    ...DEFAULT_CONFIG,
-    ...partialThemeConfig,
-  });
-}
-
 describe('themeConfig', () => {
   test('should accept valid theme config', () => {
     const userConfig = {
@@ -477,31 +468,13 @@ describe('themeConfig', () => {
   });
 
   describe('customCss config', () => {
-    test('should accept customCss undefined', () => {
-      testOk({
-        customCss: undefined,
-      });
-    });
-
-    test('should accept customCss string', () => {
-      testOk({
-        customCss: './path/to/cssFile.css',
-      });
-    });
-
-    test('should accept customCss string array', () => {
-      testOk({
-        customCss: ['./path/to/cssFile.css', './path/to/cssFile2.css'],
-      });
-    });
-
-    test('should reject customCss number', () => {
+    test('should reject customCss string', () => {
       expect(() =>
         testValidateThemeConfig({
-          customCss: 42,
+          customCss: './path/to/cssFile.css',
         }),
       ).toThrowErrorMatchingInlineSnapshot(
-        `"\\"customCss\\" must be one of [array, string]"`,
+        `"themeConfig.customCss is invalid. Custom css used to be provided as themeOptions.customCss, but it is deprecated now."`,
       );
     });
   });
diff --git a/packages/docusaurus-theme-classic/src/index.ts b/packages/docusaurus-theme-classic/src/index.ts
index 84d7079c61d1..4be8098baada 100644
--- a/packages/docusaurus-theme-classic/src/index.ts
+++ b/packages/docusaurus-theme-classic/src/index.ts
@@ -234,3 +234,4 @@ export function getSwizzleComponentList(): string[] {
 }
 
 export {validateThemeConfig} from './validateThemeConfig';
+export {validateOptions} from './options';
diff --git a/packages/docusaurus-theme-classic/src/options.ts b/packages/docusaurus-theme-classic/src/options.ts
new file mode 100644
index 000000000000..ff597fae9749
--- /dev/null
+++ b/packages/docusaurus-theme-classic/src/options.ts
@@ -0,0 +1,49 @@
+/**
+ * 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 {Joi} from '@docusaurus/utils-validation';
+import type {
+  ValidationResult,
+  OptionValidationContext,
+} from '@docusaurus/types';
+import type {Options} from '@docusaurus/theme-classic';
+
+const DEFAULT_OPTIONS: Options = {
+  customCss: null,
+};
+
+export const Schema = Joi.object({
+  customCss: Joi.alternatives()
+    .try(Joi.array().items(Joi.string().required()), Joi.string().required())
+    .optional()
+    .default(DEFAULT_OPTIONS.customCss)
+    .warning('deprecate.error', {
+      msg: `theme.customCss option is deprecated.
+Please use siteConfig.style.css instead.
+
+Note that this also changes the CSS insertion order!
+From
+
+Before: custom site CSS was inserted before Infima CSS and theme modules.
+After: custom site CSS will be inserted after Infima CSS and theme modules.
+
+This enables your site CSS to override default theme CSS more easily, without using !important
+
+See also https://github.com/facebook/docusaurus/pull/6227
+`,
+    })
+    .messages({
+      'deprecate.error': '{#msg}',
+    }),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options>): ValidationResult<Options> {
+  return validate(Schema, options);
+}
diff --git a/packages/docusaurus-theme-classic/src/theme-classic.d.ts b/packages/docusaurus-theme-classic/src/theme-classic.d.ts
index accafb0f9621..573b341b1cc8 100644
--- a/packages/docusaurus-theme-classic/src/theme-classic.d.ts
+++ b/packages/docusaurus-theme-classic/src/theme-classic.d.ts
@@ -7,7 +7,7 @@
 
 declare module '@docusaurus/theme-classic' {
   export type Options = {
-    customCss?: string | string[];
+    customCss?: string | string[] | null;
   };
 }
 
diff --git a/packages/docusaurus-theme-classic/src/validateThemeConfig.ts b/packages/docusaurus-theme-classic/src/validateThemeConfig.ts
index 1f7ca0b67f34..fff4f8468513 100644
--- a/packages/docusaurus-theme-classic/src/validateThemeConfig.ts
+++ b/packages/docusaurus-theme-classic/src/validateThemeConfig.ts
@@ -244,10 +244,6 @@ const FooterLinkItemSchema = Joi.object({
   // (users may need additional attributes like target, aria-role, data-customAttribute...)
   .unknown();
 
-const CustomCssSchema = Joi.alternatives()
-  .try(Joi.array().items(Joi.string().required()), Joi.string().required())
-  .optional();
-
 const ThemeConfigSchema = Joi.object({
   // TODO temporary (@alpha-58)
   disableDarkMode: Joi.any().forbidden().messages({
@@ -259,7 +255,13 @@ const ThemeConfigSchema = Joi.object({
     'any.unknown':
       'defaultDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.defaultMode = "dark"',
   }),
-  customCss: CustomCssSchema,
+
+  // TODO temporary
+  customCss: Joi.any().forbidden().messages({
+    'any.unknown':
+      'themeConfig.customCss is invalid. Custom css used to be provided as themeOptions.customCss, but it is deprecated now.',
+  }),
+
   colorMode: ColorModeSchema,
   image: Joi.string(),
   docs: DocsSchema,
diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts
index 219c9ecb0497..4117be0feb08 100644
--- a/packages/docusaurus-types/src/index.d.ts
+++ b/packages/docusaurus-types/src/index.d.ts
@@ -419,6 +419,7 @@ interface HtmlTagObject {
   innerHTML?: string;
 }
 
+// TODO weird useless type, refactor
 export type ValidationResult<T> = T;
 
 export type ValidationSchema<T> = Joi.ObjectSchema<T>;

From 1d3d9a1654b057e67b0deaeb067cfb9d3ad4f0d2 Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 15:30:55 +0100
Subject: [PATCH 3/7] rework deprecation warning

---
 packages/docusaurus-theme-classic/src/options.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/options.ts b/packages/docusaurus-theme-classic/src/options.ts
index ff597fae9749..c96e11c84fbf 100644
--- a/packages/docusaurus-theme-classic/src/options.ts
+++ b/packages/docusaurus-theme-classic/src/options.ts
@@ -26,13 +26,11 @@ export const Schema = Joi.object({
 Please use siteConfig.style.css instead.
 
 Note that this also changes the CSS insertion order!
-From
+This enables your site CSS to override default theme CSS more easily, without using !important
 
 Before: custom site CSS was inserted before Infima CSS and theme modules.
 After: custom site CSS will be inserted after Infima CSS and theme modules.
 
-This enables your site CSS to override default theme CSS more easily, without using !important
-
 See also https://github.com/facebook/docusaurus/pull/6227
 `,
     })

From 14340512114f9654dce4114d3e7b23ae8e601318 Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 16:06:40 +0100
Subject: [PATCH 4/7] Add config.styling.css option

---
 .../docusaurus-theme-classic/src/options.ts   |  2 +-
 packages/docusaurus-types/src/index.d.ts      |  5 +++++
 .../docusaurus/src/server/configValidation.ts | 22 ++++++++++++++++---
 packages/docusaurus/src/server/index.ts       | 19 ++++++++++++++++
 website/docusaurus.config.js                  |  5 ++++-
 website/src/css/customLegacy.css              | 12 ++++++++++
 website/testCSSOrder.js                       |  1 +
 7 files changed, 61 insertions(+), 5 deletions(-)
 create mode 100644 website/src/css/customLegacy.css

diff --git a/packages/docusaurus-theme-classic/src/options.ts b/packages/docusaurus-theme-classic/src/options.ts
index c96e11c84fbf..c45bd65f09e0 100644
--- a/packages/docusaurus-theme-classic/src/options.ts
+++ b/packages/docusaurus-theme-classic/src/options.ts
@@ -23,7 +23,7 @@ export const Schema = Joi.object({
     .default(DEFAULT_OPTIONS.customCss)
     .warning('deprecate.error', {
       msg: `theme.customCss option is deprecated.
-Please use siteConfig.style.css instead.
+Please use siteConfig.styling.css instead.
 
 Note that this also changes the CSS insertion order!
 This enables your site CSS to override default theme CSS more easily, without using !important
diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts
index 4117be0feb08..f32d57a748f1 100644
--- a/packages/docusaurus-types/src/index.d.ts
+++ b/packages/docusaurus-types/src/index.d.ts
@@ -22,6 +22,10 @@ export type ThemeConfig = {
   [key: string]: unknown;
 };
 
+export type StylingConfig = {
+  css: string[];
+};
+
 // Docusaurus config, after validation/normalization
 export interface DocusaurusConfig {
   baseUrl: string;
@@ -33,6 +37,7 @@ export interface DocusaurusConfig {
   // trailingSlash undefined = legacy retrocompatible behavior => /file => /file/index.html
   trailingSlash: boolean | undefined;
   i18n: I18nConfig;
+  styling: StylingConfig;
   onBrokenLinks: ReportingSeverity;
   onBrokenMarkdownLinks: ReportingSeverity;
   onDuplicateRoutes: ReportingSeverity;
diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts
index 0763f477228e..bd0aaeee76ac 100644
--- a/packages/docusaurus/src/server/configValidation.ts
+++ b/packages/docusaurus/src/server/configValidation.ts
@@ -6,7 +6,7 @@
  */
 
 import logger from '@docusaurus/logger';
-import {DocusaurusConfig, I18nConfig} from '@docusaurus/types';
+import {DocusaurusConfig, I18nConfig, StylingConfig} from '@docusaurus/types';
 import {DEFAULT_CONFIG_FILE_NAME, STATIC_DIR_NAME} from '@docusaurus/utils';
 import {
   Joi,
@@ -24,9 +24,14 @@ export const DEFAULT_I18N_CONFIG: I18nConfig = {
   localeConfigs: {},
 };
 
+export const DEFAULT_STYLING_CONFIG: StylingConfig = {
+  css: [],
+};
+
 export const DEFAULT_CONFIG: Pick<
   DocusaurusConfig,
   | 'i18n'
+  | 'styling'
   | 'onBrokenLinks'
   | 'onBrokenMarkdownLinks'
   | 'onDuplicateRoutes'
@@ -41,6 +46,7 @@ export const DEFAULT_CONFIG: Pick<
   | 'staticDirectories'
 > = {
   i18n: DEFAULT_I18N_CONFIG,
+  styling: DEFAULT_STYLING_CONFIG,
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
   onDuplicateRoutes: 'warn',
@@ -101,7 +107,7 @@ const LocaleConfigSchema = Joi.object({
   direction: Joi.string().equal('ltr', 'rtl').default('ltr'),
 });
 
-const I18N_CONFIG_SCHEMA = Joi.object<I18nConfig>({
+const I18nConfigSchema = Joi.object<I18nConfig>({
   defaultLocale: Joi.string().required(),
   locales: Joi.array().items().min(1).items(Joi.string().required()).required(),
   localeConfigs: Joi.object()
@@ -123,6 +129,15 @@ const SiteUrlSchema = URISchema.required().custom((value, helpers) => {
   return value;
 }, 'siteUrlCustomValidation');
 
+const StylingSchema = Joi.object({
+  css: Joi.alternatives()
+    .try(
+      Joi.array().items(Joi.string().required()).required(),
+      Joi.string().custom((val) => [val]), // normalize: string -> string[]
+    )
+    .default(DEFAULT_STYLING_CONFIG.css),
+}).default(DEFAULT_STYLING_CONFIG);
+
 // TODO move to @docusaurus/utils-validation
 export const ConfigSchema = Joi.object({
   baseUrl: Joi.string()
@@ -134,7 +149,8 @@ export const ConfigSchema = Joi.object({
   title: Joi.string().required(),
   url: SiteUrlSchema,
   trailingSlash: Joi.boolean(), // No default value! undefined = retrocompatible legacy behavior!
-  i18n: I18N_CONFIG_SCHEMA,
+  i18n: I18nConfigSchema,
+  styling: StylingSchema,
   onBrokenLinks: Joi.string()
     .equal('ignore', 'log', 'warn', 'error', 'throw')
     .default(DEFAULT_CONFIG.onBrokenLinks),
diff --git a/packages/docusaurus/src/server/index.ts b/packages/docusaurus/src/server/index.ts
index 1c18f9a4b060..1854c8ff6869 100644
--- a/packages/docusaurus/src/server/index.ts
+++ b/packages/docusaurus/src/server/index.ts
@@ -279,6 +279,22 @@ function createMDXFallbackPlugin({
   };
 }
 
+function createSiteCSSPlugin({
+  siteConfig,
+}: {
+  siteConfig: DocusaurusConfig;
+}): LoadedPlugin {
+  return {
+    name: 'docusaurus-site-styling-css-plugin',
+    content: null,
+    options: {},
+    version: {type: 'synthetic'},
+    getClientModules() {
+      return siteConfig.styling.css;
+    },
+  };
+}
+
 export async function load(
   siteDir: string,
   options: LoadContextOptions = {},
@@ -315,6 +331,9 @@ export async function load(
 
   plugins.push(createBootstrapPlugin({siteConfig}));
   plugins.push(createMDXFallbackPlugin({siteDir, siteConfig}));
+  // Added last, because the site CSS must be inserted after all other clientModules
+  // See also https://github.com/facebook/docusaurus/pull/6227
+  plugins.push(createSiteCSSPlugin({siteConfig}));
 
   // Load client modules.
   const clientModules = loadClientModules(plugins);
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 3a7771fcac38..77c572530ce8 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -76,6 +76,9 @@ const config = {
   // - force trailing slashes for deploy previews
   // - avoid trailing slashes in prod
   trailingSlash: isDeployPreview,
+  styling: {
+    css: require.resolve('./src/css/custom.css'),
+  },
   stylesheets: [
     {
       href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
@@ -304,7 +307,7 @@ const config = {
           remarkPlugins: [npm2yarn],
         },
         theme: {
-          customCss: [require.resolve('./src/css/custom.css')],
+          customCss: [require.resolve('./src/css/customLegacy.css')],
         },
         gtag: !isDeployPreview
           ? {
diff --git a/website/src/css/customLegacy.css b/website/src/css/customLegacy.css
new file mode 100644
index 000000000000..4d611a4dd0dd
--- /dev/null
+++ b/website/src/css/customLegacy.css
@@ -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.
+ */
+
+
+/* Used to test CSS insertion order */
+.test-marker-theme-custom-css-legacy {
+  content: "theme-custom-css-legacy";
+}
diff --git a/website/testCSSOrder.js b/website/testCSSOrder.js
index 72e74e36563d..6cc1af38fb30 100644
--- a/website/testCSSOrder.js
+++ b/website/testCSSOrder.js
@@ -42,6 +42,7 @@ const EXPECTED_CSS_MARKERS = [
   '.tabs__item',
 
   // Test markers
+  '.test-marker-theme-custom-css-legacy', // TODO should be removed later
   '.test-marker-site-client-module',
   '.test-marker-theme-layout',
   '.test-marker-site-index-page',

From 257e0b0aaeed2f75c817107d84aa67b945a3bf1b Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 17:32:37 +0100
Subject: [PATCH 5/7] type fix

---
 packages/docusaurus-types/src/index.d.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts
index f32d57a748f1..e46d3298badc 100644
--- a/packages/docusaurus-types/src/index.d.ts
+++ b/packages/docusaurus-types/src/index.d.ts
@@ -87,6 +87,9 @@ export type Config = Overwrite<
     url: Required<DocusaurusConfig['url']>;
     baseUrl: Required<DocusaurusConfig['baseUrl']>;
     i18n?: DeepPartial<DocusaurusConfig['i18n']>;
+    styling?: Omit<StylingConfig, 'css'> & {
+      css?: string | string[];
+    };
   }
 >;
 

From c37f5b5d541a42ae0fb13b11c6b69b5df943d4f8 Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 18:28:29 +0100
Subject: [PATCH 6/7] try to fix CSS insertion order with client-css-modules

---
 .../src/index.d.ts                            |  8 +++--
 .../docusaurus/src/client/clientEntry.tsx     |  6 ++++
 packages/docusaurus/src/server/index.ts       | 29 +++++++------------
 website/src/theme/CodeBlock/index.tsx         |  2 ++
 website/src/theme/CodeBlock/styles.module.css | 12 ++++++++
 website/src/theme/DocItem/index.tsx           | 17 +++++++++++
 website/src/theme/DocItem/styles.module.css   | 12 ++++++++
 website/testCSSOrder.js                       |  8 +++--
 8 files changed, 70 insertions(+), 24 deletions(-)
 create mode 100644 website/src/theme/CodeBlock/styles.module.css
 create mode 100644 website/src/theme/DocItem/index.tsx
 create mode 100644 website/src/theme/DocItem/styles.module.css

diff --git a/packages/docusaurus-module-type-aliases/src/index.d.ts b/packages/docusaurus-module-type-aliases/src/index.d.ts
index f3c109baf991..2c8b3778e9b8 100644
--- a/packages/docusaurus-module-type-aliases/src/index.d.ts
+++ b/packages/docusaurus-module-type-aliases/src/index.d.ts
@@ -6,11 +6,15 @@
  */
 
 declare module '@generated/client-modules' {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const clientModules: readonly any[];
+  const clientModules: readonly unknown[];
   export default clientModules;
 }
 
+declare module '@generated/css-client-modules' {
+  const cssClientModules: readonly unknown[];
+  export default cssClientModules;
+}
+
 declare module '@generated/docusaurus.config' {
   import type {DocusaurusConfig} from '@docusaurus/types';
 
diff --git a/packages/docusaurus/src/client/clientEntry.tsx b/packages/docusaurus/src/client/clientEntry.tsx
index 4742ee810569..08740ac5b4e7 100644
--- a/packages/docusaurus/src/client/clientEntry.tsx
+++ b/packages/docusaurus/src/client/clientEntry.tsx
@@ -5,6 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// import order impacts CSS insertion ordering
+// See https://github.com/facebook/docusaurus/pull/6227
+import '@generated/client-modules';
+import '@generated/registry';
+import '@generated/css-client-modules';
+
 import React from 'react';
 import {hydrate, render} from 'react-dom';
 import {BrowserRouter} from 'react-router-dom';
diff --git a/packages/docusaurus/src/server/index.ts b/packages/docusaurus/src/server/index.ts
index 1854c8ff6869..afc573777409 100644
--- a/packages/docusaurus/src/server/index.ts
+++ b/packages/docusaurus/src/server/index.ts
@@ -279,22 +279,6 @@ function createMDXFallbackPlugin({
   };
 }
 
-function createSiteCSSPlugin({
-  siteConfig,
-}: {
-  siteConfig: DocusaurusConfig;
-}): LoadedPlugin {
-  return {
-    name: 'docusaurus-site-styling-css-plugin',
-    content: null,
-    options: {},
-    version: {type: 'synthetic'},
-    getClientModules() {
-      return siteConfig.styling.css;
-    },
-  };
-}
-
 export async function load(
   siteDir: string,
   options: LoadContextOptions = {},
@@ -331,9 +315,15 @@ export async function load(
 
   plugins.push(createBootstrapPlugin({siteConfig}));
   plugins.push(createMDXFallbackPlugin({siteDir, siteConfig}));
-  // Added last, because the site CSS must be inserted after all other clientModules
-  // See also https://github.com/facebook/docusaurus/pull/6227
-  plugins.push(createSiteCSSPlugin({siteConfig}));
+
+  // Load CSS client modules
+  const genCSSClientModules = generate(
+    generatedFilesDir,
+    'css-client-modules.js',
+    `export default [\n${siteConfig.styling.css
+      .map((module) => `import('${escapePath(module)}'),`)
+      .join('\n')}\n];\n`,
+  );
 
   // Load client modules.
   const clientModules = loadClientModules(plugins);
@@ -421,6 +411,7 @@ ${Object.keys(registry)
   );
 
   await Promise.all([
+    genCSSClientModules,
     genClientModules,
     genSiteConfig,
     genRegistry,
diff --git a/website/src/theme/CodeBlock/index.tsx b/website/src/theme/CodeBlock/index.tsx
index dd5aedfc18de..f3106dd41b62 100644
--- a/website/src/theme/CodeBlock/index.tsx
+++ b/website/src/theme/CodeBlock/index.tsx
@@ -9,6 +9,8 @@ import React from 'react';
 import type {Props} from '@theme/CodeBlock';
 import CodeBlock from '@theme-original/CodeBlock';
 
+import './styles.module.css';
+
 // This component does nothing on purpose
 // Dogfood: wrapping a theme component already enhanced by another theme
 // See https://github.com/facebook/docusaurus/pull/5983
diff --git a/website/src/theme/CodeBlock/styles.module.css b/website/src/theme/CodeBlock/styles.module.css
new file mode 100644
index 000000000000..9b0583199f88
--- /dev/null
+++ b/website/src/theme/CodeBlock/styles.module.css
@@ -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.
+ */
+
+/* Used to test CSS insertion order */
+.test-marker-theme-code-block {
+  content: "theme-code-block";
+}
+
diff --git a/website/src/theme/DocItem/index.tsx b/website/src/theme/DocItem/index.tsx
new file mode 100644
index 000000000000..e8af89029d7a
--- /dev/null
+++ b/website/src/theme/DocItem/index.tsx
@@ -0,0 +1,17 @@
+/**
+ * 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 React from 'react';
+import type {Props} from '@theme/DocItem';
+import DocItem from '@theme-original/DocItem';
+
+// This component is only used to test for CSS insertion order
+import './styles.module.css';
+
+export default function DocItemWrapper(props: Props): JSX.Element {
+  return <DocItem {...props} />;
+}
diff --git a/website/src/theme/DocItem/styles.module.css b/website/src/theme/DocItem/styles.module.css
new file mode 100644
index 000000000000..4abbe838741e
--- /dev/null
+++ b/website/src/theme/DocItem/styles.module.css
@@ -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.
+ */
+
+/* Used to test CSS insertion order */
+.test-marker-theme-doc-item {
+  content: "theme-doc-item";
+}
+
diff --git a/website/testCSSOrder.js b/website/testCSSOrder.js
index 6cc1af38fb30..23591ff0d669 100644
--- a/website/testCSSOrder.js
+++ b/website/testCSSOrder.js
@@ -41,15 +41,17 @@ const EXPECTED_CSS_MARKERS = [
   '.pills__item',
   '.tabs__item',
 
-  // Test markers
+  // Markers, using Webpack require()
   '.test-marker-theme-custom-css-legacy', // TODO should be removed later
   '.test-marker-site-client-module',
   '.test-marker-theme-layout',
+
+  // Markers, using Webpack dynamic import() (routes use dynamic imports)
   '.test-marker-site-index-page',
   '.test-marker-site-custom-css-unique-rule',
-
-  // lazy loaded lib
   '.DocSearch-Modal',
+  '.test-marker-theme-code-block',
+  '.test-marker-theme-doc-item',
 ];
 
 const cssDirName = path.join(__dirname, 'build', 'assets', 'css');

From b7c6d5eb5365b3c5d5bb8eac7ae380477dd39375 Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Thu, 30 Dec 2021 18:36:17 +0100
Subject: [PATCH 7/7] warning wording

---
 packages/docusaurus-theme-classic/src/options.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/options.ts b/packages/docusaurus-theme-classic/src/options.ts
index c45bd65f09e0..97e602100a5c 100644
--- a/packages/docusaurus-theme-classic/src/options.ts
+++ b/packages/docusaurus-theme-classic/src/options.ts
@@ -28,8 +28,8 @@ Please use siteConfig.styling.css instead.
 Note that this also changes the CSS insertion order!
 This enables your site CSS to override default theme CSS more easily, without using !important
 
-Before: custom site CSS was inserted before Infima CSS and theme modules.
-After: custom site CSS will be inserted after Infima CSS and theme modules.
+Before: custom site CSS was inserted before Infima CSS and default theme CSS.
+After: custom site CSS will be inserted after Infima CSS and default theme CSS.
 
 See also https://github.com/facebook/docusaurus/pull/6227
 `,