@docusaurus/theme-classic 2.0.0-beta.1 → 2.0.0-beta.10

package/src/__tests__/validateThemeConfig.test.js

@@ -91,6 +91,10 @@ describe('themeConfig', () => {
         },
         copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
       },
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 5,
+      },
     };
     expect(testValidateThemeConfig(userConfig)).toEqual({
       ...DEFAULT_CONFIG,
@@ -108,7 +112,6 @@ describe('themeConfig', () => {
             position: 'left',
             docId: 'intro',
             label: 'Introduction',
-            activeSidebarClassName: 'custom-class',
           },
           // Regular link
           {
@@ -134,6 +137,23 @@ describe('themeConfig', () => {
               },
             ],
           },
+          // Dropdown with name
+          {
+            type: 'dropdown',
+            label: 'Tools',
+            position: 'left',
+            items: [
+              {
+                type: 'doc',
+                docId: 'npm',
+                label: 'NPM',
+              },
+              {
+                to: '/yarn',
+                label: 'Yarn',
+              },
+            ],
+          },
           // Doc version dropdown
           {
             type: 'docsVersionDropdown',
@@ -141,8 +161,7 @@ describe('themeConfig', () => {
             dropdownActiveClassDisabled: true,
             dropdownItemsBefore: [
               {
-                href:
-                  'https://www.npmjs.com/package/docusaurus?activeTab=versions',
+                href: 'https://www.npmjs.com/package/docusaurus?activeTab=versions',
                 label: 'Versions on npm',
                 className: 'npm-styled',
                 target: '_self',
@@ -181,6 +200,112 @@ describe('themeConfig', () => {
     });
   });
 
+  test('should reject unknown navbar item type', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            type: 'joke',
+            position: 'left',
+            label: 'haha',
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(`"Bad navbar item type joke"`);
+  });
+
+  test('should reject nested dropdowns', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Nested',
+            items: [
+              {
+                label: 'Still a dropdown',
+                items: [
+                  {
+                    label: 'Should reject this',
+                    to: '/rejected',
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(`"Nested dropdowns are not allowed"`);
+  });
+
+  test('should reject nested dropdowns', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Nested',
+            items: [{type: 'docsVersionDropdown'}],
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(`"Nested dropdowns are not allowed"`);
+  });
+
+  test('should reject position attribute within dropdown', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Dropdown',
+            items: [
+              {
+                label: 'Hi',
+                position: 'left',
+                to: '/link',
+              },
+            ],
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"navbar.items[0].items[0].position\\" is not allowed"`,
+    );
+  });
+
+  test('should give friendly error when href and to coexist', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Nested',
+            to: '/link',
+            href: 'http://example.com/link',
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"One and only one between \\"to\\" and \\"href\\" should be provided"`,
+    );
+  });
+
   test('should allow empty alt tags for the logo image in the header', () => {
     const altTagConfig = {
       navbar: {
@@ -220,6 +345,27 @@ describe('themeConfig', () => {
     });
   });
 
+  test('should allow width and height specification for logo ', () => {
+    const altTagConfig = {
+      navbar: {
+        logo: {
+          alt: '',
+          src: '/arbitrary-logo.png',
+          srcDark: '/arbitrary-dark-logo.png',
+          width: '20px',
+          height: '20%',
+        },
+      },
+    };
+    expect(testValidateThemeConfig(altTagConfig)).toEqual({
+      ...DEFAULT_CONFIG,
+      navbar: {
+        ...DEFAULT_CONFIG.navbar,
+        ...altTagConfig.navbar,
+      },
+    });
+  });
+
   test('should accept valid prism config', () => {
     const prismConfig = {
       prism: {
@@ -331,3 +477,131 @@ describe('themeConfig', () => {
     });
   });
 });
+
+describe('themeConfig tableOfContents', () => {
+  test('toc undefined', () => {
+    const tableOfContents = undefined;
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc empty', () => {
+    const tableOfContents = {};
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc with min', () => {
+    const tableOfContents = {
+      minHeadingLevel: 3,
+    };
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: 3,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc with max', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 5,
+    };
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: 5,
+      },
+    });
+  });
+
+  test('toc with min 2.5', () => {
+    const tableOfContents = {
+      minHeadingLevel: 2.5,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be an integer"`,
+    );
+  });
+
+  test('toc with max 2.5', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 2.5,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be an integer"`,
+    );
+  });
+
+  test('toc with min 1', () => {
+    const tableOfContents = {
+      minHeadingLevel: 1,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be greater than or equal to 2"`,
+    );
+  });
+
+  test('toc with min 7', () => {
+    const tableOfContents = {
+      minHeadingLevel: 7,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be less than or equal to ref:maxHeadingLevel"`,
+    );
+  });
+
+  test('toc with max 1', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 1,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be greater than or equal to 2"`,
+    );
+  });
+
+  test('toc with max 7', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 7,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be less than or equal to 6"`,
+    );
+  });
+
+  test('toc with bad min 5 + max 3', () => {
+    const tableOfContents = {
+      minHeadingLevel: 5,
+      maxHeadingLevel: 3,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be less than or equal to ref:maxHeadingLevel"`,
+    );
+  });
+});

package/src/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/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/index.ts

@@ -5,16 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocusaurusContext, Plugin} from '@docusaurus/types';
-import {ThemeConfig} from '@docusaurus/theme-common';
+import {DocusaurusContext, Plugin, PostCssOptions} 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';
 
-const createRequire = Module.createRequire || Module.createRequireFromPath;
 const requireFromDocusaurusCore = createRequire(
   require.resolve('@docusaurus/core/package.json'),
 );
@@ -24,9 +23,11 @@ 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 noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
-  return `(function() {
+const ThemeStorageKey = 'theme';
+const noFlashColorMode = ({
+  defaultMode,
+  respectPrefersColorScheme,
+}: ThemeConfig['colorMode']) => `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -37,7 +38,7 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
   function getStoredTheme() {
     var theme = null;
     try {
-      theme = localStorage.getItem('${storageKey}');
+      theme = localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
     return theme;
   }
@@ -61,16 +62,35 @@ 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)
+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 type PluginOptions = {
+  customCss?: string | string[];
 };
 
 export default function docusaurusThemeClassic(
@@ -82,7 +102,11 @@ export default function docusaurusThemeClassic(
     i18n: {currentLocale, localeConfigs},
   } = context;
   const themeConfig = (roughlyTypedThemeConfig || {}) as ThemeConfig;
-  const {colorMode, prism: {additionalLanguages = []} = {}} = themeConfig;
+  const {
+    announcementBar,
+    colorMode,
+    prism: {additionalLanguages = []} = {},
+  } = themeConfig;
   const {customCss} = options || {};
   const {direction} = localeConfigs[currentLocale];
 
@@ -108,12 +132,17 @@ export default function docusaurusThemeClassic(
     },
 
     getTranslationFiles: async () => getTranslationFiles({themeConfig}),
-    translateThemeConfig,
 
-    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',
       });
     },
 
@@ -121,6 +150,7 @@ export default function docusaurusThemeClassic(
       const modules = [
         require.resolve(getInfimaCSSFile(direction)),
         path.resolve(__dirname, './prism-include-languages'),
+        path.resolve(__dirname, './admonitions.css'),
       ];
 
       if (customCss) {
@@ -153,18 +183,18 @@ export default function docusaurusThemeClassic(
       };
     },
 
-    configurePostCss(postCssOptions: {plugins: AcceptedPlugin[]}) {
+    configurePostCss(postCssOptions: 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);
@@ -178,7 +208,10 @@ export default function docusaurusThemeClassic(
         preBodyTags: [
           {
             tagName: 'script',
-            innerHTML: noFlashColorMode(colorMode),
+            innerHTML: `
+${noFlashColorMode(colorMode)}
+${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+            `,
           },
         ],
       };

package/src/theme/AnnouncementBar/index.tsx

@@ -7,37 +7,30 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useThemeConfig} from '@docusaurus/theme-common';
-import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
+import {useThemeConfig, useAnnouncementBar} from '@docusaurus/theme-common';
 import {translate} from '@docusaurus/Translate';
+import IconClose from '@theme/IconClose';
 
 import styles from './styles.module.css';
 
 function AnnouncementBar(): JSX.Element | null {
-  const {
-    isAnnouncementBarClosed,
-    closeAnnouncementBar,
-  } = useUserPreferencesContext();
+  const {isActive, close} = useAnnouncementBar();
   const {announcementBar} = useThemeConfig();
 
-  if (!announcementBar) {
+  if (!isActive) {
     return null;
   }
 
-  const {content, backgroundColor, textColor, isCloseable} = announcementBar;
-  if (!content || (isCloseable && isAnnouncementBarClosed)) {
-    return null;
-  }
+  const {content, backgroundColor, textColor, isCloseable} = announcementBar!;
 
   return (
     <div
       className={styles.announcementBar}
       style={{backgroundColor, color: textColor}}
       role="banner">
+      {isCloseable && <div className={styles.announcementBarPlaceholder} />}
       <div
-        className={clsx(styles.announcementBarContent, {
-          [styles.announcementBarCloseable]: isCloseable,
-        })}
+        className={styles.announcementBarContent}
         // Developer provided the HTML, so assume it's safe.
         // eslint-disable-next-line react/no-danger
         dangerouslySetInnerHTML={{__html: content}}
@@ -45,14 +38,14 @@ function AnnouncementBar(): JSX.Element | null {
       {isCloseable ? (
         <button
           type="button"
-          className={clsx(styles.announcementBarClose, 'clean-btn')}
-          onClick={closeAnnouncementBar}
+          className={clsx('clean-btn close', styles.announcementBarClose)}
+          onClick={close}
           aria-label={translate({
             id: 'theme.AnnouncementBar.closeButtonAriaLabel',
             message: 'Close',
             description: 'The ARIA label for close button of announcement bar',
           })}>
-          <span aria-hidden="true">×</span>
+          <IconClose width={14} height={14} strokeWidth={3.1} />
         </button>
       ) : null}
     </div>

package/src/theme/AnnouncementBar/styles.module.css

@@ -10,55 +10,39 @@
 }
 
 .announcementBar {
-  position: relative;
-  width: 100%;
+  display: flex;
+  align-items: center;
   height: var(--docusaurus-announcement-bar-height);
   background-color: var(--ifm-color-white);
   color: var(--ifm-color-black);
   border-bottom: 1px solid var(--ifm-color-emphasis-100);
 }
 
-@media print {
-  .announcementBar {
-    display: none;
-  }
+html[data-announcement-bar-initially-dismissed='true'] .announcementBar {
+  display: none;
 }
 
-@media screen and (min-width: 1024px) {
-  :root {
-    --docusaurus-announcement-bar-height: 30px;
-  }
+.announcementBarPlaceholder {
+  flex: 0 0 10px;
 }
 
 .announcementBarClose {
-  position: absolute;
-  right: 0;
-  top: 0;
-  width: 55px;
-  font-size: 1.25rem;
-  height: 100%;
+  flex: 0 0 30px;
+  align-self: stretch;
+  padding: 0;
+  line-height: 0;
 }
 
 .announcementBarContent {
+  flex: 1 1 auto;
   font-size: 85%;
-  width: 100%;
   text-align: center;
   padding: 5px 0;
 }
 
-.announcementBarCloseable {
-  margin-right: 55px;
-}
-
-@media screen and (max-width: 576px) {
-  .announcementBarClose {
-    width: 35px;
-  }
-  .announcementBarContent {
-    width: auto;
-  }
-  .announcementBarCloseable {
-    margin-right: 35px;
+@media print {
+  .announcementBar {
+    display: none;
   }
 }
 
@@ -66,3 +50,14 @@
   color: inherit;
   text-decoration: underline;
 }
+
+@media (min-width: 997px) {
+  :root {
+    --docusaurus-announcement-bar-height: 30px;
+  }
+
+  .announcementBarPlaceholder,
+  .announcementBarClose {
+    flex-basis: 50px;
+  }
+}