@docusaurus/theme-classic 2.0.0-beta.15d451942 → 2.0.0-beta.18

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/admonitions.css

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+
+.admonition h5 {
+  margin-top: 0;
+  margin-bottom: 8px;
+  text-transform: uppercase;
+}
+
+.admonition-icon {
+  display: inline-block;
+  vertical-align: middle;
+  margin-right: 0.4em;
+}
+
+.admonition-icon svg {
+  display: inline-block;
+  width: 22px;
+  height: 22px;
+  stroke-width: 0;
+  fill: var(--ifm-alert-foreground-color);
+  stroke: var(--ifm-alert-foreground-color);
+}
+
+.admonition-content > :last-child {
+  margin-bottom: 0;
+}
+
+.admonition {
+  margin-bottom: 1em;
+}

package/lib/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/lib/getSwizzleConfig.js

@@ -0,0 +1,236 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = getSwizzleConfig;
+
+/**
+ * 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.
+ */
+
+/* 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',
+          // 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'
+      },
+      // 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/lib/index.js

@@ -3,8 +3,14 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.AnnouncementBarDismissStorageKey = void 0;
 exports.default = docusaurusThemeClassic;
-exports.getSwizzleComponentList = getSwizzleComponentList;
+Object.defineProperty(exports, "getSwizzleConfig", {
+  enumerable: true,
+  get: function () {
+    return _getSwizzleConfig.default;
+  }
+});
 Object.defineProperty(exports, "validateThemeConfig", {
   enumerable: true,
   get: function () {
@@ -14,13 +20,13 @@ Object.defineProperty(exports, "validateThemeConfig", {
 
 var _translations = require("./translations");
 
-var _path = _interopRequireDefault(require("path"));
-
-var _module = _interopRequireDefault(require("module"));
+var _module = require("module");
 
 var _rtlcss = _interopRequireDefault(require("rtlcss"));
 
-var _utils = require("@docusaurus/utils");
+var _themeTranslations = require("@docusaurus/theme-translations");
+
+var _getSwizzleConfig = _interopRequireDefault(require("./getSwizzleConfig"));
 
 var _validateThemeConfig = require("./validateThemeConfig");
 
@@ -32,18 +38,16 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * 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 requireFromDocusaurusCore = (0, _module.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`
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
 
-const storageKey = 'theme';
+const ThemeStorageKey = 'theme';
 
 const noFlashColorMode = ({
   defaultMode,
   respectPrefersColorScheme
-}) => {
-  return `(function() {
+}) => `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -54,7 +58,7 @@ const noFlashColorMode = ({
   function getStoredTheme() {
     var theme = null;
     try {
-      theme = localStorage.getItem('${storageKey}');
+      theme = localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
     return theme;
   }
@@ -77,70 +81,82 @@ const noFlashColorMode = ({
       setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
     }
   }
+})();`; // 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
+
+
+const AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
+exports.AnnouncementBarDismissStorageKey = AnnouncementBarDismissStorageKey;
+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)
+
+const AnnouncementBarInlineJavaScript = `
+(function() {
+  function isDismissed() {
+    try {
+      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
 })();`;
-};
 
 function getInfimaCSSFile(direction) {
   return `infima/dist/css/default/default${direction === 'rtl' ? '-rtl' : ''}.css`;
 }
 
-function docusaurusThemeClassic(context, // TODO: LoadContext is missing some of properties
-options) {
+function docusaurusThemeClassic(context, options) {
   const {
-    siteConfig: {
-      themeConfig: roughlyTypedThemeConfig
-    },
     i18n: {
       currentLocale,
       localeConfigs
     }
   } = context;
-  const themeConfig = roughlyTypedThemeConfig || {};
+  const themeConfig = context.siteConfig.themeConfig;
   const {
+    announcementBar,
     colorMode,
     prism: {
-      additionalLanguages = []
-    } = {}
+      additionalLanguages
+    }
   } = themeConfig;
   const {
     customCss
-  } = options || {};
+  } = 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');
+      return '../lib-next/theme';
     },
 
     getTypeScriptThemePath() {
-      return _path.default.resolve(__dirname, '..', 'src', 'theme');
+      return '../src/theme';
     },
 
     getTranslationFiles: async () => (0, _translations.getTranslationFiles)({
       themeConfig
     }),
-    translateThemeConfig: _translations.translateThemeConfig,
-    getDefaultCodeTranslationMessages: () => {
-      return (0, _utils.readDefaultCodeTranslationMessages)({
-        dirPath: _path.default.resolve(__dirname, '..', 'codeTranslations'),
-        locale: currentLocale
+    translateThemeConfig: params => (0, _translations.translateThemeConfig)({
+      themeConfig: params.themeConfig,
+      translationFiles: params.translationFiles
+    }),
+
+    getDefaultCodeTranslationMessages() {
+      return (0, _themeTranslations.readDefaultCodeTranslationMessages)({
+        locale: currentLocale,
+        name: 'theme-common'
       });
     },
 
     getClientModules() {
-      const modules = [require.resolve(getInfimaCSSFile(direction)), _path.default.resolve(__dirname, './prism-include-languages')];
+      const modules = [require.resolve(getInfimaCSSFile(direction)), './prism-include-languages', './admonitions.css'];
 
       if (customCss) {
         if (Array.isArray(customCss)) {
@@ -156,9 +172,10 @@ options) {
     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})$`))]
+        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})$`))]
       };
     },
 
@@ -190,19 +207,13 @@ options) {
       return {
         preBodyTags: [{
           tagName: 'script',
-          attributes: {
-            type: 'text/javascript'
-          },
-          innerHTML: noFlashColorMode(colorMode)
+          innerHTML: `
+${noFlashColorMode(colorMode)}
+${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+            `
         }]
       };
     }
 
   };
-}
-
-const swizzleAllowedComponents = ['CodeBlock', 'DocSidebar', 'Footer', 'NotFound', 'SearchBar', 'IconArrow', 'IconEdit', 'IconMenu', 'hooks/useTheme', 'prism-include-languages'];
-
-function getSwizzleComponentList() {
-  return swizzleAllowedComponents;
 }

package/lib/prism-include-languages.js

@@ -1,11 +1,15 @@
+"use strict";
+
+var _prism = _interopRequireDefault(require("prism-react-renderer/prism"));
+
+var _prismIncludeLanguages = _interopRequireDefault(require("@theme/prism-include-languages"));
+
+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.
  */
-
-import Prism from 'prism-react-renderer/prism';
-import prismIncludeLanguages from '@theme/prism-include-languages';
-
-prismIncludeLanguages(Prism);
+(0, _prismIncludeLanguages.default)(_prism.default);