@docusaurus/theme-classic 2.0.0-beta.2 → 2.0.0-beta.20

package/src/deps.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+declare module 'prism-react-renderer/prism' {
+  import type * as PrismNamespace from 'prismjs';
+
+  const Prism: typeof PrismNamespace;
+  export default Prism;
+}

package/src/getSwizzleConfig.ts

@@ -0,0 +1,252 @@
+/**
+ * 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',
+      },
+      IconArrow: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The arrow icon component',
+      },
+      IconDarkMode: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The dark mode icon component.',
+      },
+      IconEdit: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The edit icon component',
+      },
+      IconLightMode: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The light mode icon component.',
+      },
+      IconMenu: {
+        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.',
+      },
+      // TODO should probably not even appear here
+      'NavbarItem/utils': {
+        actions: {
+          eject: 'forbidden',
+          wrap: 'forbidden',
+        },
+      },
+      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,29 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocusaurusContext, Plugin} from '@docusaurus/types';
+import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {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 type {Plugin as PostCssPlugin} from 'postcss';
 import rtlcss from 'rtlcss';
-import {readDefaultCodeTranslationMessages} from '@docusaurus/utils';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {Options} 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',
-);
+const ContextReplacementPlugin: typeof webpack.ContextReplacementPlugin =
+  requireFromDocusaurusCore('webpack/lib/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`
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
 const ThemeStorageKey = 'theme';
-const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
-  return `(function() {
+const noFlashColorMode = ({
+  defaultMode,
+  respectPrefersColorScheme,
+}: ThemeConfig['colorMode']) => `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -61,17 +62,18 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
     }
   }
 })();`;
-};
 
-// Duplicated constant. Unfortunately we can't import it from theme-common, as we need to support older nodejs versions without ESM support
+// 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)
+// 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)
 const AnnouncementBarInlineJavaScript = `
 (function() {
   function isDismissed() {
@@ -83,68 +85,60 @@ const AnnouncementBarInlineJavaScript = `
   document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
 })();`;
 
-function getInfimaCSSFile(direction) {
+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
-  options: PluginOptions,
-): Plugin<void> {
+export default function themeClassic(
+  context: LoadContext,
+  options: Options,
+): Plugin<undefined> {
   const {
-    siteConfig: {themeConfig: roughlyTypedThemeConfig},
     i18n: {currentLocale, localeConfigs},
   } = context;
-  const themeConfig = (roughlyTypedThemeConfig || {}) as ThemeConfig;
+  const themeConfig = context.siteConfig.themeConfig as ThemeConfig;
   const {
     announcementBar,
     colorMode,
-    prism: {additionalLanguages = []} = {},
+    prism: {additionalLanguages},
   } = themeConfig;
-  const {customCss} = options || {};
-  const {direction} = localeConfigs[currentLocale];
+  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-next/theme';
     },
 
     getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
+      return '../src/theme';
     },
 
-    getTranslationFiles: async () => getTranslationFiles({themeConfig}),
-    translateThemeConfig,
+    getTranslationFiles: () => getTranslationFiles({themeConfig}),
 
-    getDefaultCodeTranslationMessages: () => {
+    translateThemeConfig: (params) =>
+      translateThemeConfig({
+        themeConfig: params.themeConfig as ThemeConfig,
+        translationFiles: params.translationFiles,
+      }),
+
+    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',
+        './admonitions.css',
+        './nprogress',
       ];
 
       if (customCss) {
@@ -164,11 +158,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})$`),
@@ -177,18 +170,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) => {
+          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);
@@ -213,21 +206,5 @@ ${announcementBar ? AnnouncementBarInlineJavaScript : ''}
   };
 }
 
-const swizzleAllowedComponents = [
-  'CodeBlock',
-  'DocSidebar',
-  'Footer',
-  'NotFound',
-  'SearchBar',
-  'IconArrow',
-  'IconEdit',
-  'IconMenu',
-  'hooks/useTheme',
-  'prism-include-languages',
-];
-
-export function getSwizzleComponentList(): string[] {
-  return swizzleAllowedComponents;
-}
-
+export {default as getSwizzleConfig} from './getSwizzleConfig';
 export {validateThemeConfig} from './validateThemeConfig';

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;

package/src/theme/Admonition/index.tsx

@@ -0,0 +1,106 @@
+/**
+ * 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 clsx from 'clsx';
+import type {Props} from '@theme/Admonition';
+
+const icons = {
+  note: (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="16"
+      viewBox="0 0 14 16">
+      <path
+        fillRule="evenodd"
+        d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"
+      />
+    </svg>
+  ),
+  tip: (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="12"
+      height="16"
+      viewBox="0 0 12 16">
+      <path
+        fillRule="evenodd"
+        d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"
+      />
+    </svg>
+  ),
+  danger: (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="12"
+      height="16"
+      viewBox="0 0 12 16">
+      <path
+        fillRule="evenodd"
+        d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"
+      />
+    </svg>
+  ),
+  info: (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="16"
+      viewBox="0 0 14 16">
+      <path
+        fillRule="evenodd"
+        d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"
+      />
+    </svg>
+  ),
+  caution: (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 16 16">
+      <path
+        fillRule="evenodd"
+        d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"
+      />
+    </svg>
+  ),
+};
+
+const ifmClassNames = {
+  note: 'secondary',
+  tip: 'success',
+  danger: 'danger',
+  info: 'info',
+  caution: 'warning',
+};
+
+export default function Admonition({
+  children,
+  type,
+  title = type,
+  icon = icons[type],
+}: Props): JSX.Element {
+  return (
+    <div
+      className={clsx(
+        'admonition',
+        `admonition-${type}`,
+        'alert',
+        `alert--${ifmClassNames[type]}`,
+      )}>
+      <div className="admonition-heading">
+        <h5>
+          <span className="admonition-icon">{icon}</span>
+          {title}
+        </h5>
+      </div>
+      <div className="admonition-content">{children}</div>
+    </div>
+  );
+}