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 44275d476ad3..5a1c26ad4eb4 100644 --- a/packages/docusaurus-theme-classic/src/index.js +++ b/packages/docusaurus-theme-classic/src/index.js @@ -20,41 +20,49 @@ 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() { - var defaultDarkMode = ${defaultDarkMode}; +const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => { + return `(function() { + var defaultMode = '${defaultMode}'; + var respectPrefersColorScheme = ${respectPrefersColorScheme}; 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 ( + respectPrefersColorScheme && + window.matchMedia('(prefers-color-scheme: dark)').matches + ) { + setDataThemeAttribute('dark'); + } else if ( + respectPrefersColorScheme && + window.matchMedia('(prefers-color-scheme: light)').matches + ) { + setDataThemeAttribute('light'); + } else { + setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light'); + } } })();`; +}; module.exports = function (context, options) { const { siteConfig: {themeConfig}, } = context; - const { - disableDarkMode = false, - defaultDarkMode = false, - prism: {additionalLanguages = []} = {}, - } = themeConfig || {}; + const {colorMode, prism: {additionalLanguages = []} = {}} = themeConfig || {}; const {customCss} = options || {}; return { @@ -97,9 +105,6 @@ module.exports = function (context, options) { }, injectHtmlTags() { - if (disableDarkMode) { - return {}; - } return { preBodyTags: [ { @@ -107,7 +112,7 @@ module.exports = function (context, options) { attributes: { type: 'text/javascript', }, - innerHTML: noFlash(defaultDarkMode), + innerHTML: noFlashColorMode(colorMode), }, ], }; @@ -130,8 +135,26 @@ 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.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: ColorModeSchema, image: Joi.string(), announcementBar: Joi.object({ id: Joi.string(), diff --git a/packages/docusaurus-theme-classic/src/theme/Navbar/index.tsx b/packages/docusaurus-theme-classic/src/theme/Navbar/index.tsx index 798a4139f08a..b7723923bfb3 100644 --- a/packages/docusaurus-theme-classic/src/theme/Navbar/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/Navbar/index.tsx @@ -185,7 +185,7 @@ function Navbar(): JSX.Element { siteConfig: { themeConfig: { navbar: {title = '', links = [], hideOnScroll = false} = {}, - disableDarkMode = false, + colorMode: {disableSwitch: disableColorModeSwitch = false} = {}, }, }, isClient, @@ -283,7 +283,7 @@ function Navbar(): JSX.Element { {rightLinks.map((linkItem, i) => ( ))} - {!disableDarkMode && ( + {!disableColorModeSwitch && ( {title} )} - {!disableDarkMode && sidebarShown && ( + {!disableColorModeSwitch && sidebarShown && ( { + return theme === themes.dark ? themes.dark : themes.light; +}; + +const getInitialTheme = () => { + if (!ExecutionEnvironment.canUseDOM) { + 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 = (): { isDarkTheme: boolean; setLightTheme: () => void; setDarkTheme: () => void; } => { const { - siteConfig: {themeConfig: {disableDarkMode = false} = {}} = {}, + 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(() => { - // @ts-expect-error: safe to set null as attribute - 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); @@ -67,7 +76,7 @@ const useTheme = (): { }, [setTheme]); useEffect(() => { - if (disableDarkMode) { + if (disableSwitch) { return; } 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/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; } ``` diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md index 2f7f41340e9d..985be7049ef7 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, + // Should we use the prefers-color-scheme media-query, + // using user system preferences, instead of the hardcoded defaultMode + respectPrefersColorScheme: false, + }, // ... }, + // ... }; ``` +:::caution + +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. + +::: + ### 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 1567e83c7f5d..a1265a01fa14 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -81,6 +81,11 @@ module.exports = { ], ], themeConfig: { + colorMode: { + defaultMode: 'light', + disableSwitch: false, + respectPrefersColorScheme: true, + }, announcementBar: { id: 'supportus', content: