colorMode validation + deprecation + minor name changes + doc

facebook · Jun 29, 2020 · f3eb4d3 · f3eb4d3
1 parent 31c6cfd
commit f3eb4d3
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 26 deletions.
diff --git 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
@@ -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
@@ -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
@@ -82,11 +82,10 @@ module.exports = {
   ],
   themeConfig: {
     colorMode: {
-      defaultDarkMode: false,
-      respectUserPreference: true,
+      defaultMode: 'light',
+      respectPrefersColorScheme: true,
       disableSwitch: false,
     },
-
     announcementBar: {
       id: 'supportus',
       content: