From d917e084f5e5581e31c9ab5804e879b41d0a6b06 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 15 Jun 2020 19:25:31 +0200
Subject: [PATCH 01/10] refactor color mode system to enable all possibilities

---
 .../docusaurus-theme-classic/src/index.js     | 40 +++++++------
 .../src/theme/Navbar/index.js                 |  6 +-
 .../src/theme/hooks/useTheme.js               | 57 +++++++++++--------
 website/docusaurus.config.js                  |  6 ++
 4 files changed, 67 insertions(+), 42 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js
index cbe3e4c91410..a1be6709cb6e 100644
--- a/packages/docusaurus-theme-classic/src/index.js
+++ b/packages/docusaurus-theme-classic/src/index.js
@@ -19,39 +19,47 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
 const storageKey = 'theme';
-const noFlash = (defaultDarkMode) => `(function() {
+const noFlash = ({defaultDarkMode = false, respectUserPreference = false}) => {
+  return `(function() {
   var defaultDarkMode = ${defaultDarkMode};
+  var respectUserPreference = ${respectUserPreference};
 
   function setDataThemeAttribute(theme) {
     document.documentElement.setAttribute('data-theme', theme);
   }
 
-  function getPreferredTheme() {
+  function getStoredTheme() {
     var theme = null;
     try {
       theme = localStorage.getItem('${storageKey}');
     } catch (err) {}
-
     return theme;
   }
 
-  var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
-
-  var preferredTheme = getPreferredTheme();
-  if (preferredTheme !== null) {
-    setDataThemeAttribute(preferredTheme);
-  } else if (darkQuery.matches || defaultDarkMode) {
-    setDataThemeAttribute('dark');
+  var storedTheme = getStoredTheme();
+  if (storedTheme !== null) {
+    setDataThemeAttribute(storedTheme);
+  }
+  else {
+    if ( respectUserPreference && window.matchMedia('(prefers-color-scheme: dark)').matches ) {
+      setDataThemeAttribute('dark');
+    }
+    else if ( respectUserPreference && window.matchMedia('(prefers-color-scheme: light)').matches ) {
+      setDataThemeAttribute('light');
+    }
+    else {
+      setDataThemeAttribute(defaultDarkMode ? 'dark' : 'light');
+    }
   }
 })();`;
+};
 
 module.exports = function (context, options) {
   const {
     siteConfig: {themeConfig},
   } = context;
   const {
-    disableDarkMode = false,
-    defaultDarkMode = false,
+    colorMode: {defaultDarkMode = false, respectUserPreference = false} = {},
     prism: {additionalLanguages = []} = {},
   } = themeConfig || {};
   const {customCss} = options || {};
@@ -92,9 +100,6 @@ module.exports = function (context, options) {
     },
 
     injectHtmlTags() {
-      if (disableDarkMode) {
-        return {};
-      }
       return {
         preBodyTags: [
           {
@@ -102,7 +107,10 @@ module.exports = function (context, options) {
             attributes: {
               type: 'text/javascript',
             },
-            innerHTML: noFlash(defaultDarkMode),
+            innerHTML: noFlash({
+              defaultDarkMode,
+              respectUserPreference,
+            }),
           },
         ],
       };
diff --git a/packages/docusaurus-theme-classic/src/theme/Navbar/index.js b/packages/docusaurus-theme-classic/src/theme/Navbar/index.js
index 5edee09174ff..2cde1dbbfe50 100644
--- a/packages/docusaurus-theme-classic/src/theme/Navbar/index.js
+++ b/packages/docusaurus-theme-classic/src/theme/Navbar/index.js
@@ -175,7 +175,7 @@ function Navbar() {
     siteConfig: {
       themeConfig: {
         navbar: {title, links = [], hideOnScroll = false} = {},
-        disableDarkMode = false,
+        colorMode: {disableSwitch: disableColorModeSwitch = false} = {},
       },
     },
     isClient,
@@ -265,7 +265,7 @@ function Navbar() {
           {rightLinks.map((linkItem, i) => (
             <NavItem {...linkItem} key={i} />
           ))}
-          {!disableDarkMode && (
+          {!disableColorModeSwitch && (
             <Toggle
               className={styles.displayOnlyInLargeViewport}
               aria-label="Dark mode toggle"
@@ -303,7 +303,7 @@ function Navbar() {
               <strong className="navbar__title">{title}</strong>
             )}
           </Link>
-          {!disableDarkMode && sidebarShown && (
+          {!disableColorModeSwitch && sidebarShown && (
             <Toggle
               aria-label="Dark mode toggle in sidebar"
               checked={isDarkTheme}
diff --git a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
index a0bd4e6d046a..e6566f5b2a71 100644
--- a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
+++ b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
@@ -10,51 +10,62 @@ import {useState, useCallback, useEffect} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 const themes = {
-  light: '',
+  light: 'light',
   dark: 'dark',
 };
 
+// Ensure to always return a valid theme even if input is invalid
+const coerceToTheme = (theme) => {
+  return theme === themes.dark ? themes.dark : themes.light;
+};
+
+const getInitialTheme = () => {
+  if (typeof document === 'undefined') {
+    return themes.light; // SSR: we don't care
+  }
+  return coerceToTheme(document.documentElement.getAttribute('data-theme'));
+};
+
+const storeTheme = (newTheme) => {
+  try {
+    localStorage.setItem('theme', coerceToTheme(newTheme));
+  } catch (err) {
+    console.error(err);
+  }
+};
+
 const useTheme = () => {
   const {
-    siteConfig: {themeConfig: {disableDarkMode}} = {},
+    siteConfig: {
+      themeConfig: {
+        colorMode: {disableSwitch = false},
+      },
+    } = {},
   } = useDocusaurusContext();
-  const [theme, setTheme] = useState(
-    typeof document !== 'undefined'
-      ? document.documentElement.getAttribute('data-theme')
-      : themes.light,
-  );
-  const setThemeSyncWithLocalStorage = useCallback(
-    (newTheme) => {
-      try {
-        localStorage.setItem('theme', newTheme);
-      } catch (err) {
-        console.error(err);
-      }
-    },
-    [setTheme],
-  );
+  const [theme, setTheme] = useState(getInitialTheme);
+
   const setLightTheme = useCallback(() => {
     setTheme(themes.light);
-    setThemeSyncWithLocalStorage(themes.light);
+    storeTheme(themes.light);
   }, []);
   const setDarkTheme = useCallback(() => {
     setTheme(themes.dark);
-    setThemeSyncWithLocalStorage(themes.dark);
+    storeTheme(themes.dark);
   }, []);
 
   useEffect(() => {
-    document.documentElement.setAttribute('data-theme', theme);
+    document.documentElement.setAttribute('data-theme', coerceToTheme(theme));
   }, [theme]);
 
   useEffect(() => {
-    if (disableDarkMode) {
+    if (disableSwitch) {
       return;
     }
 
     try {
       const localStorageTheme = localStorage.getItem('theme');
       if (localStorageTheme !== null) {
-        setTheme(localStorageTheme);
+        setTheme(coerceToTheme(localStorageTheme));
       }
     } catch (err) {
       console.error(err);
@@ -62,7 +73,7 @@ const useTheme = () => {
   }, [setTheme]);
 
   useEffect(() => {
-    if (disableDarkMode) {
+    if (disableSwitch) {
       return;
     }
 
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 43c06f7943ef..ae19bb45d676 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -81,6 +81,12 @@ module.exports = {
     ],
   ],
   themeConfig: {
+    colorMode: {
+      defaultDarkMode: false,
+      respectUserPreference: true,
+      disableSwitch: false,
+    },
+
     announcementBar: {
       id: 'supportus',
       content:

From 263766816b54c64e8e05fb359dd0cb84bead8a3d Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 15 Jun 2020 19:46:48 +0200
Subject: [PATCH 02/10] fix destructuring bug

---
 .../docusaurus-theme-classic/src/theme/hooks/useTheme.js    | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
index e6566f5b2a71..cfc4562309d8 100644
--- a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
+++ b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
@@ -36,11 +36,7 @@ const storeTheme = (newTheme) => {
 
 const useTheme = () => {
   const {
-    siteConfig: {
-      themeConfig: {
-        colorMode: {disableSwitch = false},
-      },
-    } = {},
+    siteConfig: {themeConfig: {colorMode: {disableSwitch = false} = {}}} = {},
   } = useDocusaurusContext();
   const [theme, setTheme] = useState(getInitialTheme);
 

From f3eb4d322a1f6bb2672c4e0690e469f8a387170e Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 17:53:02 +0200
Subject: [PATCH 03/10] colorMode validation + deprecation + minor name changes
 + doc

---
 .prettierignore                               |  1 +
 .../docusaurus-theme-classic/src/index.js     | 32 +++++++++++-----
 website/docs/theme-classic.md                 | 37 ++++++++++++-------
 website/docusaurus.config.js                  |  5 +--
 4 files changed, 49 insertions(+), 26 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index 1f599c7c1a41..a4e8eef74d6e 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -14,4 +14,5 @@ packages/docusaurus-plugin-content-pages/lib/
 packages/docusaurus-plugin-debug/lib/
 packages/docusaurus-plugin-sitemap/lib/
 packages/docusaurus-plugin-ideal-image/lib/
+packages/docusaurus-theme-classic/lib/
 __fixtures__
diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js
index f2ec62e4d31d..145a19d986ba 100644
--- a/packages/docusaurus-theme-classic/src/index.js
+++ b/packages/docusaurus-theme-classic/src/index.js
@@ -20,10 +20,10 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
 const storageKey = 'theme';
-const noFlash = ({defaultDarkMode = false, respectUserPreference = false}) => {
+const noFlash = ({defaultMode, respectPrefersColorScheme}) => {
   return `(function() {
-  var defaultDarkMode = ${defaultDarkMode};
-  var respectUserPreference = ${respectUserPreference};
+  var defaultMode = ${defaultMode};
+  var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
   function setDataThemeAttribute(theme) {
     document.documentElement.setAttribute('data-theme', theme);
@@ -42,14 +42,14 @@ const noFlash = ({defaultDarkMode = false, respectUserPreference = false}) => {
     setDataThemeAttribute(storedTheme);
   }
   else {
-    if ( respectUserPreference && window.matchMedia('(prefers-color-scheme: dark)').matches ) {
+    if ( respectPrefersColorScheme && window.matchMedia('(prefers-color-scheme: dark)').matches ) {
       setDataThemeAttribute('dark');
     }
-    else if ( respectUserPreference && window.matchMedia('(prefers-color-scheme: light)').matches ) {
+    else if ( respectPrefersColorScheme && window.matchMedia('(prefers-color-scheme: light)').matches ) {
       setDataThemeAttribute('light');
     }
     else {
-      setDataThemeAttribute(defaultDarkMode ? 'dark' : 'light');
+      setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
     }
   }
 })();`;
@@ -60,7 +60,7 @@ module.exports = function (context, options) {
     siteConfig: {themeConfig},
   } = context;
   const {
-    colorMode: {defaultDarkMode = false, respectUserPreference = false} = {},
+    colorMode: {defaultMode, respectPrefersColorScheme} = {},
     prism: {additionalLanguages = []} = {},
   } = themeConfig || {};
   const {customCss} = options || {};
@@ -113,8 +113,8 @@ module.exports = function (context, options) {
               type: 'text/javascript',
             },
             innerHTML: noFlash({
-              defaultDarkMode,
-              respectUserPreference,
+              defaultMode,
+              respectPrefersColorScheme,
             }),
           },
         ],
@@ -139,7 +139,19 @@ const NavbarLinkSchema = Joi.object({
   .id('navbarLinkSchema');
 
 const ThemeConfigSchema = Joi.object({
-  disableDarkMode: Joi.bool().default(false),
+  disableDarkMode: Joi.any().forbidden(false).messages({
+    'any.unknown':
+      'disableDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.disableSwitch = true',
+  }),
+  defaultDarkMode: Joi.any().forbidden(false).messages({
+    'any.unknown':
+      'defaultDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.defaultMode = "dark"',
+  }),
+  colorMode: Joi.object({
+    defaultMode: Joi.string().equal('dark', 'light').default('light'),
+    respectPrefersColorScheme: Joi.bool().default(false),
+    disableSwitch: Joi.bool().default(false),
+  }),
   image: Joi.string(),
   announcementBar: Joi.object({
     id: Joi.string(),
diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md
index 2f7f41340e9d..a9a5d1dfe942 100644
--- a/website/docs/theme-classic.md
+++ b/website/docs/theme-classic.md
@@ -11,32 +11,43 @@ This section is a work in progress.
 
 ## Common
 
-### Dark mode
+### Color mode - dark mode
 
-To remove the ability to switch on dark mode, there is an option `themeConfig.disableDarkMode`, which is implicitly set to `false`.
+The classic theme provides by default light and dark mode support, with a navbar switch for the user.
 
-```js {4} title="docusaurus.config.js"
+It is possible to customize the color mode support with the following configuration:
+
+```js {6-15} title="docusaurus.config.js"
 module.exports = {
   // ...
   themeConfig: {
-    disableDarkMode: false,
     // ...
-  },
-};
-```
+    colorMode: {
+      // "light" | "dark"
+      defaultMode: 'light',
 
-With the enabled `defaultDarkMode` option you could set dark mode by default. However, in this case, the user's preference will not be taken into account until they manually sets the desired mode via toggle in the navbar.
+      // Hides the switch in the navbar
+      // Useful if you want to support a single color mode
+      disableSwitch: false,
 
-```js {4} title="docusaurus.config.js"
-module.exports = {
-  // ...
-  themeConfig: {
-    defaultDarkMode: true,
+      // If available, should we use the prefers-color-scheme media-query
+      // (instead of the hardcoded defaultMode)
+      respectPrefersColorScheme: false,
+    },
     // ...
   },
+  // ...
 };
 ```
 
+:::caution
+
+With `respectPrefersColorScheme: true`, the `defaultMode` is overriden by user system preferences.
+
+You probably don't want this behavior if you only support one color mode (`disableSwitch: false`)
+
+:::
+
 ### Meta image
 
 You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index ae19bb45d676..8864d211452e 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -82,11 +82,10 @@ module.exports = {
   ],
   themeConfig: {
     colorMode: {
-      defaultDarkMode: false,
-      respectUserPreference: true,
+      defaultMode: 'light',
+      respectPrefersColorScheme: true,
       disableSwitch: false,
     },
-
     announcementBar: {
       id: 'supportus',
       content:

From 534df68b8a30478bd49be385b03c0000cdcfb0f6 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 17:56:36 +0200
Subject: [PATCH 04/10] rename method noFlashColorMode

---
 packages/docusaurus-theme-classic/src/index.js | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js
index 145a19d986ba..015aa0c0bdf5 100644
--- a/packages/docusaurus-theme-classic/src/index.js
+++ b/packages/docusaurus-theme-classic/src/index.js
@@ -20,7 +20,7 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
 const storageKey = 'theme';
-const noFlash = ({defaultMode, respectPrefersColorScheme}) => {
+const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
   return `(function() {
   var defaultMode = ${defaultMode};
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
@@ -59,10 +59,7 @@ module.exports = function (context, options) {
   const {
     siteConfig: {themeConfig},
   } = context;
-  const {
-    colorMode: {defaultMode, respectPrefersColorScheme} = {},
-    prism: {additionalLanguages = []} = {},
-  } = themeConfig || {};
+  const {colorMode, prism: {additionalLanguages = []} = {}} = themeConfig || {};
   const {customCss} = options || {};
 
   return {
@@ -112,10 +109,7 @@ module.exports = function (context, options) {
             attributes: {
               type: 'text/javascript',
             },
-            innerHTML: noFlash({
-              defaultMode,
-              respectPrefersColorScheme,
-            }),
+            innerHTML: noFlashColorMode(colorMode),
           },
         ],
       };

From 3b6716fcf7be7e812fe4f8877f9d88940c3e739a Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 18:01:58 +0200
Subject: [PATCH 05/10] fix doc wording

---
 website/docs/theme-classic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md
index a9a5d1dfe942..abd6c59ce82e 100644
--- a/website/docs/theme-classic.md
+++ b/website/docs/theme-classic.md
@@ -44,7 +44,7 @@ module.exports = {
 
 With `respectPrefersColorScheme: true`, the `defaultMode` is overriden by user system preferences.
 
-You probably don't want this behavior if you only support one color mode (`disableSwitch: false`)
+You probably don't want this behavior if you only want to support one color mode, and use `disableSwitch: true`.
 
 :::
 

From ef6a2267ca8e3f061cbdd883a0251ae5c8f1715f Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 18:03:14 +0200
Subject: [PATCH 06/10] docs wording

---
 website/docs/theme-classic.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md
index abd6c59ce82e..8c53e755fe3a 100644
--- a/website/docs/theme-classic.md
+++ b/website/docs/theme-classic.md
@@ -30,8 +30,8 @@ module.exports = {
       // Useful if you want to support a single color mode
       disableSwitch: false,
 
-      // If available, should we use the prefers-color-scheme media-query
-      // (instead of the hardcoded defaultMode)
+      // Should we use the prefers-color-scheme media-query,
+      // using user system preferences, instead of the hardcoded defaultMode
       respectPrefersColorScheme: false,
     },
     // ...

From af0072cd737b36a32473f40cbdd2474495620406 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 18:05:28 +0200
Subject: [PATCH 07/10] docs wording

---
 website/docs/theme-classic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md
index 8c53e755fe3a..0458fba933fe 100644
--- a/website/docs/theme-classic.md
+++ b/website/docs/theme-classic.md
@@ -44,7 +44,7 @@ module.exports = {
 
 With `respectPrefersColorScheme: true`, the `defaultMode` is overriden by user system preferences.
 
-You probably don't want this behavior if you only want to support one color mode, and use `disableSwitch: true`.
+If you only want to support one color mode, you likely want to ignore user system preferences.
 
 :::
 

From 63ae6c8ad38070c0a098d9b968584042ec2ce93e Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 18:19:27 +0200
Subject: [PATCH 08/10] re-enable theme config merging/normalization +
 colorMode fixes

---
 packages/docusaurus-theme-classic/src/index.js | 18 ++++++++++++------
 packages/docusaurus/src/server/plugins/init.ts | 11 ++++++++---
 website/docusaurus.config.js                   |  2 +-
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js
index 015aa0c0bdf5..20b9f1bc3148 100644
--- a/packages/docusaurus-theme-classic/src/index.js
+++ b/packages/docusaurus-theme-classic/src/index.js
@@ -22,7 +22,7 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 const storageKey = 'theme';
 const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
   return `(function() {
-  var defaultMode = ${defaultMode};
+  var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
   function setDataThemeAttribute(theme) {
@@ -132,6 +132,16 @@ const NavbarLinkSchema = Joi.object({
   .xor('href', 'to')
   .id('navbarLinkSchema');
 
+const ColorModeSchema = Joi.object({
+  defaultMode: Joi.string().equal('dark', 'light').default('light'),
+  disableSwitch: Joi.bool().default(false),
+  respectPrefersColorScheme: Joi.bool().default(false),
+}).default({
+  defaultMode: 'light',
+  disableSwitch: false,
+  respectPrefersColorScheme: false,
+});
+
 const ThemeConfigSchema = Joi.object({
   disableDarkMode: Joi.any().forbidden(false).messages({
     'any.unknown':
@@ -141,11 +151,7 @@ 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"',
   }),
-  colorMode: Joi.object({
-    defaultMode: Joi.string().equal('dark', 'light').default('light'),
-    respectPrefersColorScheme: Joi.bool().default(false),
-    disableSwitch: Joi.bool().default(false),
-  }),
+  colorMode: ColorModeSchema,
   image: Joi.string(),
   announcementBar: Joi.object({
     id: Joi.string(),
diff --git a/packages/docusaurus/src/server/plugins/init.ts b/packages/docusaurus/src/server/plugins/init.ts
index 0cde6e9f168e..11b0fee25524 100644
--- a/packages/docusaurus/src/server/plugins/init.ts
+++ b/packages/docusaurus/src/server/plugins/init.ts
@@ -83,11 +83,11 @@ export default function initPlugins({
         pluginModule.default?.validateOptions ?? pluginModule.validateOptions;
 
       if (validateOptions) {
-        const options = validateOptions({
+        const normalizedOptions = validateOptions({
           validate,
           options: pluginOptions,
         });
-        pluginOptions = options;
+        pluginOptions = normalizedOptions;
       }
 
       // support both commonjs and ES modules
@@ -96,10 +96,15 @@ export default function initPlugins({
         pluginModule.validateThemeConfig;
 
       if (validateThemeConfig) {
-        validateThemeConfig({
+        const normalizedThemeConfig = validateThemeConfig({
           validate: validateAndStrip,
           themeConfig: context.siteConfig.themeConfig,
         });
+
+        context.siteConfig.themeConfig = {
+          ...context.siteConfig.themeConfig,
+          ...normalizedThemeConfig,
+        };
       }
       return plugin(context, pluginOptions);
     })
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 8864d211452e..512da3ffecd3 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -83,8 +83,8 @@ module.exports = {
   themeConfig: {
     colorMode: {
       defaultMode: 'light',
-      respectPrefersColorScheme: true,
       disableSwitch: false,
+      respectPrefersColorScheme: true,
     },
     announcementBar: {
       id: 'supportus',

From 2c75ee1770dc78045a5abfb064eba5b2321ee7db Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 29 Jun 2020 18:25:33 +0200
Subject: [PATCH 09/10] document theme normalization

---
 website/docs/lifecycle-apis.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/website/docs/lifecycle-apis.md b/website/docs/lifecycle-apis.md
index 68d43fd4f150..2baaeb3444a2 100644
--- a/website/docs/lifecycle-apis.md
+++ b/website/docs/lifecycle-apis.md
@@ -63,11 +63,11 @@ export function validateOptions({options, validate}) {
 
 ## `validateThemeConfig({themeConfig,validate})`
 
-Validate `themeConfig` for the plugins and theme. This method is called before the plugin is initialized.
+Return validated and normalized configuration for the theme.
 
 ### `themeConfig`
 
-`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation.
+`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization.
 
 ### `validate`
 
@@ -75,7 +75,7 @@ Validate `themeConfig` for the plugins and theme. This method is called before t
 
 :::tip
 
-[Joi](https://www.npmjs.com/package/@hapi/joi) is recommended for validation and normalization of options.
+[Joi](https://www.npmjs.com/package/@hapi/joi) is recommended for validation and normalization of theme config.
 
 :::
 
@@ -90,7 +90,8 @@ module.exports = function (context, options) {
 };
 
 module.exports.validateThemeConfig = ({themeConfig, validate}) => {
-  validate(myValidationSchema, options);
+  const validatedThemeConfig = validate(myValidationSchema, options);
+  return validatedThemeConfig;
 };
 ```
 
@@ -105,7 +106,8 @@ export default function (context, options) {
 }
 
 export function validateThemeConfig({themeConfig, validate}) {
-  validate(myValidationSchema, options);
+  const validatedThemeConfig = validate(myValidationSchema, options);
+  return validatedThemeConfig;
 }
 ```
 

From c352eefb804cf3e01ffb6ce5390fc7840d1179c4 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Tue, 30 Jun 2020 12:08:31 +0200
Subject: [PATCH 10/10] code review changes

---
 packages/docusaurus-theme-classic/src/index.js  | 17 ++++++++++-------
 .../src/theme/hooks/useTheme.ts                 |  3 ++-
 website/docs/theme-classic.md                   |  2 +-
 3 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js
index 20b9f1bc3148..5a1c26ad4eb4 100644
--- a/packages/docusaurus-theme-classic/src/index.js
+++ b/packages/docusaurus-theme-classic/src/index.js
@@ -40,15 +40,18 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
   var storedTheme = getStoredTheme();
   if (storedTheme !== null) {
     setDataThemeAttribute(storedTheme);
-  }
-  else {
-    if ( respectPrefersColorScheme && window.matchMedia('(prefers-color-scheme: dark)').matches ) {
+  } else {
+    if (
+      respectPrefersColorScheme &&
+      window.matchMedia('(prefers-color-scheme: dark)').matches
+    ) {
       setDataThemeAttribute('dark');
-    }
-    else if ( respectPrefersColorScheme && window.matchMedia('(prefers-color-scheme: light)').matches ) {
+    } else if (
+      respectPrefersColorScheme &&
+      window.matchMedia('(prefers-color-scheme: light)').matches
+    ) {
       setDataThemeAttribute('light');
-    }
-    else {
+    } else {
       setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
     }
   }
diff --git a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.ts b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.ts
index 705d0106e1b6..bbb45bfe9ade 100644
--- a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.ts
+++ b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.ts
@@ -8,6 +8,7 @@
 import {useState, useCallback, useEffect} from 'react';
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 
 const themes = {
   light: 'light',
@@ -20,7 +21,7 @@ const coerceToTheme = (theme) => {
 };
 
 const getInitialTheme = () => {
-  if (typeof document === 'undefined') {
+  if (!ExecutionEnvironment.canUseDOM) {
     return themes.light; // SSR: we don't care
   }
   return coerceToTheme(document.documentElement.getAttribute('data-theme'));
diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md
index 0458fba933fe..985be7049ef7 100644
--- a/website/docs/theme-classic.md
+++ b/website/docs/theme-classic.md
@@ -42,7 +42,7 @@ module.exports = {
 
 :::caution
 
-With `respectPrefersColorScheme: true`, the `defaultMode` is overriden by user system preferences.
+With `respectPrefersColorScheme: true`, the `defaultMode` is overridden by user system preferences.
 
 If you only want to support one color mode, you likely want to ignore user system preferences.