@docusaurus/theme-classic 2.0.0-beta.ff31de0ff → 2.0.0-rc.1

package/src/getSwizzleConfig.ts

@@ -0,0 +1,245 @@
+/**
+ * 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 type {SwizzleConfig} from '@docusaurus/types';
+
+/* eslint sort-keys: "error" */
+
+export default function getSwizzleConfig(): SwizzleConfig {
+  return {
+    components: {
+      CodeBlock: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component used to render multi-line code blocks, generally used in Markdown files.',
+      },
+      ColorModeToggle: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The color mode toggle to switch between light and dark mode.',
+      },
+      DocSidebar: {
+        actions: {
+          eject: 'unsafe', // Too much technical code in sidebar, not very safe atm
+          wrap: 'safe',
+        },
+        description: 'The sidebar component on docs pages',
+      },
+      Footer: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: "The footer component of you site's layout",
+      },
+      'Footer/Copyright': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The footer copyright',
+      },
+      'Footer/Layout': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The footer main layout component',
+      },
+      'Footer/LinkItem': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The footer link item component',
+      },
+      'Footer/Links': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The footer component rendering the footer links',
+      },
+      'Footer/Links/MultiColumn': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The footer component rendering the footer links with a multi-column layout',
+      },
+      'Footer/Links/Simple': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The footer component rendering the footer links with a simple layout (single row)',
+      },
+      'Footer/Logo': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The footer logo',
+      },
+      'Icon/Arrow': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The arrow icon component',
+      },
+      'Icon/DarkMode': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The dark mode icon component.',
+      },
+      'Icon/Edit': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The edit icon component',
+      },
+      'Icon/LightMode': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The light mode icon component.',
+      },
+      'Icon/Menu': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The menu icon component',
+      },
+      MDXComponents: {
+        actions: {
+          eject: 'safe',
+          wrap: 'forbidden', /// TODO allow wrapping objects???
+        },
+        description:
+          'The MDX components to use for rendering MDX files. Meant to be ejected.',
+      },
+      'MDXComponents/A': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component used to render <a> tags and Markdown links in MDX',
+      },
+      'MDXComponents/Code': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component used to render <code> tags and Markdown code blocks in MDX',
+      },
+      'MDXComponents/Details': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The component used to render <details> tags in MDX',
+      },
+      'MDXComponents/Head': {
+        actions: {
+          eject: 'forbidden',
+          wrap: 'forbidden',
+        },
+        description:
+          'Technical component used to assign metadata (generally for SEO purpose) to the current MDX document',
+      },
+      'MDXComponents/Heading': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component used to render heading tags (<h1>, <h2>...) and Markdown headings in MDX',
+      },
+      'MDXComponents/Img': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component used to render <img> tags and Markdown images in MDX',
+      },
+      'MDXComponents/Pre': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The component used to render <pre> tags in MDX',
+      },
+      'MDXComponents/Ul': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component used to render <ul> tags and Markdown unordered lists in MDX',
+      },
+      MDXContent: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'A component wrapping all MDX content and providing the MDXComponents to the MDX context',
+      },
+      'NavbarItem/ComponentTypes': {
+        actions: {
+          eject: 'safe',
+          wrap: 'forbidden',
+        },
+        description:
+          'The Navbar item components mapping. Can be ejected to add custom navbar item types. See https://github.com/facebook/docusaurus/issues/7227.',
+      },
+      NotFound: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The global 404 page of your site, meant to be ejected and customized',
+      },
+      SearchBar: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        // TODO how to describe this one properly?
+        // By default it's an empty placeholder for the user to fill
+        description:
+          'The search bar component of your site, appearing in the navbar.',
+      },
+      'prism-include-languages': {
+        actions: {
+          eject: 'safe',
+          wrap: 'forbidden', // Not a component!
+        },
+        description:
+          'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',
+      },
+    },
+  };
+}

package/src/index.ts

@@ -5,28 +5,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocusaurusContext, Plugin} from '@docusaurus/types';
-import {ThemeConfig} from '@docusaurus/theme-common';
-import {getTranslationFiles, translateThemeConfig} from './translations';
 import path from 'path';
-import Module from 'module';
-import type {AcceptedPlugin, Result, Plugin as PostCssPlugin} from 'postcss';
+import {createRequire} from 'module';
 import rtlcss from 'rtlcss';
-import {readDefaultCodeTranslationMessages} from '@docusaurus/utils';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import {getTranslationFiles, translateThemeConfig} from './translations';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {ThemeConfig} from '@docusaurus/theme-common';
+import type {Plugin as PostCssPlugin} from 'postcss';
+import type {PluginOptions} from '@docusaurus/theme-classic';
+import type webpack from 'webpack';
 
-const createRequire = Module.createRequire || Module.createRequireFromPath;
 const requireFromDocusaurusCore = createRequire(
   require.resolve('@docusaurus/core/package.json'),
 );
 const ContextReplacementPlugin = requireFromDocusaurusCore(
   'webpack/lib/ContextReplacementPlugin',
-);
+) as typeof webpack.ContextReplacementPlugin;
 
 // 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 noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
-  return `(function() {
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
+const ThemeStorageKey = 'theme';
+const noFlashColorMode = ({
+  defaultMode,
+  respectPrefersColorScheme,
+}: ThemeConfig['colorMode']) =>
+  /* language=js */
+  `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -37,7 +42,7 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
   function getStoredTheme() {
     var theme = null;
     try {
-      theme = localStorage.getItem('${storageKey}');
+      theme = localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
     return theme;
   }
@@ -61,75 +66,86 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
     }
   }
 })();`;
-};
 
-function getInfimaCSSFile(direction) {
+// Duplicated constant. Unfortunately we can't import it from theme-common, as
+// we need to support older nodejs versions without ESM support
+// TODO: import from theme-common once we only support Node.js with ESM support
+// + move all those announcementBar stuff there too
+export const AnnouncementBarDismissStorageKey =
+  'docusaurus.announcement.dismiss';
+const AnnouncementBarDismissDataAttribute =
+  'data-announcement-bar-initially-dismissed';
+// We always render the announcement bar html on the server, to prevent layout
+// shifts on React hydration. The theme can use CSS + the data attribute to hide
+// the announcement bar asap (before React hydration)
+/* language=js */
+const AnnouncementBarInlineJavaScript = `
+(function() {
+  function isDismissed() {
+    try {
+      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
+})();`;
+
+function getInfimaCSSFile(direction: string) {
   return `infima/dist/css/default/default${
     direction === 'rtl' ? '-rtl' : ''
   }.css`;
 }
 
-type PluginOptions = {
-  customCss?: string;
-};
-
-export default function docusaurusThemeClassic(
-  context: DocusaurusContext, // TODO: LoadContext is missing some of properties
+export default function themeClassic(
+  context: LoadContext,
   options: PluginOptions,
-): Plugin<void> {
+): Plugin<undefined> {
   const {
-    siteConfig: {themeConfig: roughlyTypedThemeConfig},
     i18n: {currentLocale, localeConfigs},
   } = context;
-  const themeConfig = (roughlyTypedThemeConfig || {}) as ThemeConfig;
-  const {colorMode, prism: {additionalLanguages = []} = {}} = themeConfig;
-  const {customCss} = options || {};
-  const {direction} = localeConfigs[currentLocale];
+  const themeConfig = context.siteConfig.themeConfig as ThemeConfig;
+  const {
+    announcementBar,
+    colorMode,
+    prism: {additionalLanguages},
+  } = themeConfig;
+  const {customCss} = options;
+  const {direction} = localeConfigs[currentLocale]!;
 
   return {
     name: 'docusaurus-theme-classic',
 
-    /*
-    Does not seem needed: webpack can already hot reload theme files
-    getPathsToWatch() {
-      return [
-        path.join(__dirname, '..', 'lib'),
-        path.join(__dirname, '..', 'lib-next'),
-      ];
-    },
-     */
-
     getThemePath() {
-      return path.join(__dirname, '..', 'lib-next', 'theme');
+      return '../lib/theme';
     },
 
     getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
+      return '../src/theme';
     },
 
-    getTranslationFiles: async () => getTranslationFiles({themeConfig}),
-    translateThemeConfig,
+    getTranslationFiles: () => getTranslationFiles({themeConfig}),
+
+    translateThemeConfig: (params) =>
+      translateThemeConfig({
+        themeConfig: params.themeConfig as ThemeConfig,
+        translationFiles: params.translationFiles,
+      }),
 
-    getDefaultCodeTranslationMessages: () => {
+    getDefaultCodeTranslationMessages() {
       return readDefaultCodeTranslationMessages({
-        dirPath: path.resolve(__dirname, '..', 'codeTranslations'),
         locale: currentLocale,
+        name: 'theme-common',
       });
     },
 
     getClientModules() {
       const modules = [
         require.resolve(getInfimaCSSFile(direction)),
-        path.resolve(__dirname, './prism-include-languages'),
+        './prism-include-languages',
+        './nprogress',
       ];
 
-      if (customCss) {
-        if (Array.isArray(customCss)) {
-          modules.push(...customCss);
-        } else {
-          modules.push(customCss);
-        }
-      }
+      modules.push(...customCss.map((p) => path.resolve(context.siteDir, p)));
 
       return modules;
     },
@@ -140,11 +156,10 @@ export default function docusaurusThemeClassic(
         .join('|');
 
       return {
-        ignoreWarnings: [
-          // See https://github.com/facebook/docusaurus/pull/3382
-          (e) => e.message.includes("Can't resolve '@theme-init/hooks/useDocs"),
-        ],
         plugins: [
+          // This allows better optimization by only bundling those components
+          // that the user actually needs, because the modules are dynamically
+          // required and can't be known during compile time.
           new ContextReplacementPlugin(
             /prismjs[\\/]components$/,
             new RegExp(`^./(${prismLanguages})$`),
@@ -153,18 +168,18 @@ export default function docusaurusThemeClassic(
       };
     },
 
-    configurePostCss(postCssOptions: {plugins: AcceptedPlugin[]}) {
+    configurePostCss(postCssOptions) {
       if (direction === 'rtl') {
         const resolvedInfimaFile = require.resolve(getInfimaCSSFile(direction));
         const plugin: PostCssPlugin = {
           postcssPlugin: 'RtlCssPlugin',
-          prepare: (result: Result) => {
-            const file = result.root?.source?.input?.file;
+          prepare: (result) => {
+            const file = result.root.source?.input.file;
             // Skip Infima as we are using the its RTL version.
             if (file === resolvedInfimaFile) {
               return {};
             }
-            return rtlcss(result.root);
+            return rtlcss(result.root as unknown as rtlcss.ConfigOptions);
           },
         };
         postCssOptions.plugins.push(plugin);
@@ -178,10 +193,10 @@ export default function docusaurusThemeClassic(
         preBodyTags: [
           {
             tagName: 'script',
-            attributes: {
-              type: 'text/javascript',
-            },
-            innerHTML: noFlashColorMode(colorMode),
+            innerHTML: `
+${noFlashColorMode(colorMode)}
+${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+            `,
           },
         ],
       };
@@ -189,21 +204,5 @@ export default function docusaurusThemeClassic(
   };
 }
 
-const swizzleAllowedComponents = [
-  'CodeBlock',
-  'DocSidebar',
-  'Footer',
-  'NotFound',
-  'SearchBar',
-  'IconArrow',
-  'IconEdit',
-  'IconMenu',
-  'hooks/useTheme',
-  'prism-include-languages',
-];
-
-export function getSwizzleComponentList(): string[] {
-  return swizzleAllowedComponents;
-}
-
-export {validateThemeConfig} from './validateThemeConfig';
+export {default as getSwizzleConfig} from './getSwizzleConfig';
+export {validateThemeConfig, validateOptions} from './options';

package/src/nprogress.css

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+
+/**
+ * Styles for NProgress
+ * Copied over to remove unused styles for the spinner.
+ * https://github.com/rstacruz/nprogress/blob/master/nprogress.css
+ */
+
+:root {
+  --docusaurus-progress-bar-color: var(--ifm-color-primary);
+}
+
+#nprogress {
+  pointer-events: none;
+}
+
+#nprogress .bar {
+  background: var(--docusaurus-progress-bar-color);
+  position: fixed;
+  z-index: 1031;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 2px;
+}
+
+#nprogress .peg {
+  position: absolute;
+  right: 0;
+  width: 100px;
+  height: 100%;
+  box-shadow: 0 0 10px var(--docusaurus-progress-bar-color),
+    0 0 5px var(--docusaurus-progress-bar-color);
+  opacity: 1;
+  transform: rotate(3deg) translate(0, -4px);
+}

package/src/nprogress.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 nprogress from 'nprogress';
+import './nprogress.css';
+import type {ClientModule} from '@docusaurus/types';
+
+nprogress.configure({showSpinner: false});
+
+const delay = 200;
+
+const clientModule: ClientModule = {
+  onRouteUpdate({location, previousLocation}) {
+    if (previousLocation && location.pathname !== previousLocation.pathname) {
+      const progressBarTimeout = window.setTimeout(() => {
+        nprogress.start();
+      }, delay);
+      return () => window.clearTimeout(progressBarTimeout);
+    }
+    return undefined;
+  },
+  onRouteDidUpdate() {
+    nprogress.done();
+  },
+};
+
+export default clientModule;