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

package/README.md

@@ -24,8 +24,8 @@ module.exports = {
 
 ## Swizzling components
 
-```shell
+```bash
 $ npm swizzle @docusaurus/theme-classic [component name]
 ```
 
-All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/src/theme)
+All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme)

package/lib/getSwizzleConfig.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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';
+export default function getSwizzleConfig(): SwizzleConfig;

package/lib/getSwizzleConfig.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint sort-keys: "error" */
+function getSwizzleConfig() {
+    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',
+                    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.',
+            },
+        },
+    };
+}
+exports.default = getSwizzleConfig;

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 { LoadContext, Plugin } from '@docusaurus/types';
+import type { PluginOptions } from '@docusaurus/theme-classic';
+export declare const AnnouncementBarDismissStorageKey = "docusaurus.announcement.dismiss";
+export default function themeClassic(context: LoadContext, options: PluginOptions): Plugin<undefined>;
+export { default as getSwizzleConfig } from './getSwizzleConfig';
+export { validateThemeConfig, validateOptions } from './options';

package/lib/index.js

@@ -1,49 +1,26 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = docusaurusThemeClassic;
-exports.getSwizzleComponentList = getSwizzleComponentList;
-Object.defineProperty(exports, "validateThemeConfig", {
-  enumerable: true,
-  get: function () {
-    return _validateThemeConfig.validateThemeConfig;
-  }
-});
-
-var _translations = require("./translations");
-
-var _path = _interopRequireDefault(require("path"));
-
-var _module = _interopRequireDefault(require("module"));
-
-var _rtlcss = _interopRequireDefault(require("rtlcss"));
-
-var _utils = require("@docusaurus/utils");
-
-var _validateThemeConfig = require("./validateThemeConfig");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
 /**
  * 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.
  */
-const createRequire = _module.default.createRequire || _module.default.createRequireFromPath;
-const requireFromDocusaurusCore = createRequire(require.resolve('@docusaurus/core/package.json'));
-const 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`
-
-const storageKey = 'theme';
-
-const noFlashColorMode = ({
-  defaultMode,
-  respectPrefersColorScheme
-}) => {
-  return `(function() {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptions = exports.validateThemeConfig = exports.getSwizzleConfig = exports.AnnouncementBarDismissStorageKey = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const module_1 = require("module");
+const rtlcss_1 = tslib_1.__importDefault(require("rtlcss"));
+const theme_translations_1 = require("@docusaurus/theme-translations");
+const translations_1 = require("./translations");
+const requireFromDocusaurusCore = (0, module_1.createRequire)(require.resolve('@docusaurus/core/package.json'));
+const ContextReplacementPlugin = requireFromDocusaurusCore('webpack/lib/ContextReplacementPlugin');
+// Need to be inlined to prevent dark mode FOUC
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
+const ThemeStorageKey = 'theme';
+const noFlashColorMode = ({ defaultMode, respectPrefersColorScheme, }) => 
+/* language=js */
+`(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -54,7 +31,7 @@ const noFlashColorMode = ({
   function getStoredTheme() {
     var theme = null;
     try {
-      theme = localStorage.getItem('${storageKey}');
+      theme = localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
     return theme;
   }
@@ -78,131 +55,112 @@ const noFlashColorMode = ({
     }
   }
 })();`;
-};
-
+// 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
+exports.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('${exports.AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
+})();`;
 function getInfimaCSSFile(direction) {
-  return `infima/dist/css/default/default${direction === 'rtl' ? '-rtl' : ''}.css`;
+    return `infima/dist/css/default/default${direction === 'rtl' ? '-rtl' : ''}.css`;
 }
-
-function docusaurusThemeClassic(context, // TODO: LoadContext is missing some of properties
-options) {
-  const {
-    siteConfig: {
-      themeConfig: roughlyTypedThemeConfig
-    },
-    i18n: {
-      currentLocale,
-      localeConfigs
-    }
-  } = context;
-  const themeConfig = roughlyTypedThemeConfig || {};
-  const {
-    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.default.join(__dirname, '..', 'lib-next', 'theme');
-    },
-
-    getTypeScriptThemePath() {
-      return _path.default.resolve(__dirname, '..', 'src', 'theme');
-    },
-
-    getTranslationFiles: async () => (0, _translations.getTranslationFiles)({
-      themeConfig
-    }),
-    translateThemeConfig: _translations.translateThemeConfig,
-    getDefaultCodeTranslationMessages: () => {
-      return (0, _utils.readDefaultCodeTranslationMessages)({
-        dirPath: _path.default.resolve(__dirname, '..', 'codeTranslations'),
-        locale: currentLocale
-      });
-    },
-
-    getClientModules() {
-      const modules = [require.resolve(getInfimaCSSFile(direction)), _path.default.resolve(__dirname, './prism-include-languages')];
-
-      if (customCss) {
-        if (Array.isArray(customCss)) {
-          modules.push(...customCss);
-        } else {
-          modules.push(customCss);
-        }
-      }
-
-      return modules;
-    },
-
-    configureWebpack() {
-      const prismLanguages = additionalLanguages.map(lang => `prism-${lang}`).join('|');
-      return {
-        ignoreWarnings: [// See https://github.com/facebook/docusaurus/pull/3382
-        e => e.message.includes("Can't resolve '@theme-init/hooks/useDocs")],
-        plugins: [new ContextReplacementPlugin(/prismjs[\\/]components$/, new RegExp(`^./(${prismLanguages})$`))]
-      };
-    },
-
-    configurePostCss(postCssOptions) {
-      if (direction === 'rtl') {
-        const resolvedInfimaFile = require.resolve(getInfimaCSSFile(direction));
-
-        const plugin = {
-          postcssPlugin: 'RtlCssPlugin',
-          prepare: result => {
-            var _result$root, _result$root$source, _result$root$source$i;
-
-            const file = (_result$root = result.root) === null || _result$root === void 0 ? void 0 : (_result$root$source = _result$root.source) === null || _result$root$source === void 0 ? void 0 : (_result$root$source$i = _result$root$source.input) === null || _result$root$source$i === void 0 ? void 0 : _result$root$source$i.file; // Skip Infima as we are using the its RTL version.
-
-            if (file === resolvedInfimaFile) {
-              return {};
+function themeClassic(context, options) {
+    const { i18n: { currentLocale, localeConfigs }, } = context;
+    const themeConfig = context.siteConfig.themeConfig;
+    const { announcementBar, colorMode, prism: { additionalLanguages }, } = themeConfig;
+    const { customCss } = options;
+    const { direction } = localeConfigs[currentLocale];
+    return {
+        name: 'docusaurus-theme-classic',
+        getThemePath() {
+            return '../lib/theme';
+        },
+        getTypeScriptThemePath() {
+            return '../src/theme';
+        },
+        getTranslationFiles: () => (0, translations_1.getTranslationFiles)({ themeConfig }),
+        translateThemeConfig: (params) => (0, translations_1.translateThemeConfig)({
+            themeConfig: params.themeConfig,
+            translationFiles: params.translationFiles,
+        }),
+        getDefaultCodeTranslationMessages() {
+            return (0, theme_translations_1.readDefaultCodeTranslationMessages)({
+                locale: currentLocale,
+                name: 'theme-common',
+            });
+        },
+        getClientModules() {
+            const modules = [
+                require.resolve(getInfimaCSSFile(direction)),
+                './prism-include-languages',
+                './nprogress',
+            ];
+            modules.push(...customCss.map((p) => path_1.default.resolve(context.siteDir, p)));
+            return modules;
+        },
+        configureWebpack() {
+            const prismLanguages = additionalLanguages
+                .map((lang) => `prism-${lang}`)
+                .join('|');
+            return {
+                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})$`)),
+                ],
+            };
+        },
+        configurePostCss(postCssOptions) {
+            if (direction === 'rtl') {
+                const resolvedInfimaFile = require.resolve(getInfimaCSSFile(direction));
+                const plugin = {
+                    postcssPlugin: 'RtlCssPlugin',
+                    prepare: (result) => {
+                        const file = result.root.source?.input.file;
+                        // Skip Infima as we are using the its RTL version.
+                        if (file === resolvedInfimaFile) {
+                            return {};
+                        }
+                        return (0, rtlcss_1.default)(result.root);
+                    },
+                };
+                postCssOptions.plugins.push(plugin);
             }
-
-            return (0, _rtlcss.default)(result.root);
-          }
-        };
-        postCssOptions.plugins.push(plugin);
-      }
-
-      return postCssOptions;
-    },
-
-    injectHtmlTags() {
-      return {
-        preBodyTags: [{
-          tagName: 'script',
-          attributes: {
-            type: 'text/javascript'
-          },
-          innerHTML: noFlashColorMode(colorMode)
-        }]
-      };
-    }
-
-  };
+            return postCssOptions;
+        },
+        injectHtmlTags() {
+            return {
+                preBodyTags: [
+                    {
+                        tagName: 'script',
+                        innerHTML: `
+${noFlashColorMode(colorMode)}
+${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+            `,
+                    },
+                ],
+            };
+        },
+    };
 }
-
-const swizzleAllowedComponents = ['CodeBlock', 'DocSidebar', 'Footer', 'NotFound', 'SearchBar', 'IconArrow', 'IconEdit', 'IconMenu', 'hooks/useTheme', 'prism-include-languages'];
-
-function getSwizzleComponentList() {
-  return swizzleAllowedComponents;
-}
+exports.default = themeClassic;
+var getSwizzleConfig_1 = require("./getSwizzleConfig");
+Object.defineProperty(exports, "getSwizzleConfig", { enumerable: true, get: function () { return tslib_1.__importDefault(getSwizzleConfig_1).default; } });
+var options_1 = require("./options");
+Object.defineProperty(exports, "validateThemeConfig", { enumerable: true, get: function () { return options_1.validateThemeConfig; } });
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/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/lib/nprogress.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.css';
+import type { ClientModule } from '@docusaurus/types';
+declare const clientModule: ClientModule;
+export default clientModule;

package/lib/nprogress.js

@@ -0,0 +1,25 @@
+/**
+ * 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';
+nprogress.configure({ showSpinner: false });
+const delay = 200;
+const 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/lib/options.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { Joi } from '@docusaurus/utils-validation';
+import type { Options, PluginOptions } from '@docusaurus/theme-classic';
+import type { ThemeConfig } from '@docusaurus/theme-common';
+import type { ThemeConfigValidationContext, OptionValidationContext } from '@docusaurus/types';
+export declare const DEFAULT_CONFIG: ThemeConfig;
+export declare const ThemeConfigSchema: Joi.ObjectSchema<ThemeConfig>;
+export declare function validateThemeConfig({ validate, themeConfig, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;
+export declare function validateOptions({ validate, options, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;