@docusaurus/theme-classic 2.0.0-beta.14 → 2.0.0-beta.15

package/README.md

@@ -24,7 +24,7 @@ module.exports = {
 
 ## Swizzling components
 
-```shell
+```bash
 $ npm swizzle @docusaurus/theme-classic [component name]
 ```
 

package/lib/index.js

@@ -101,8 +101,7 @@ 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
@@ -129,21 +128,12 @@ options) {
   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 _path.default.join(__dirname, '../lib-next/theme');
     },
 
     getTypeScriptThemePath() {
-      return _path.default.resolve(__dirname, '..', 'src', 'theme');
+      return _path.default.resolve(__dirname, '../src/theme');
     },
 
     getTranslationFiles: async () => (0, _translations.getTranslationFiles)({
@@ -178,9 +168,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})$`))]
       };
     },
 

package/lib/theme-classic.d.ts

@@ -44,7 +44,8 @@ declare module '@theme/BlogListPaginator' {
 }
 
 declare module '@theme/BlogPostItem' {
-  import type {FrontMatter, Assets, Metadata} from '@theme/BlogPostPage';
+  import type {FrontMatter, Metadata} from '@theme/BlogPostPage';
+  import type {Assets} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     readonly frontMatter: FrontMatter;
@@ -70,7 +71,8 @@ declare module '@theme/BlogPostAuthor' {
 }
 
 declare module '@theme/BlogPostAuthors' {
-  import type {Metadata, Assets} from '@theme/BlogPostPage';
+  import type {Metadata} from '@theme/BlogPostPage';
+  import type {Assets} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     readonly authors: Metadata['authors'];
@@ -107,13 +109,14 @@ declare module '@theme/BlogLayout' {
 }
 
 declare module '@theme/CodeBlock' {
-  import {ReactElement} from 'react';
+  import type {ReactElement} from 'react';
 
   export interface Props {
     readonly children: string | ReactElement;
     readonly className?: string;
     readonly metastring?: string;
     readonly title?: string;
+    readonly language?: string;
   }
 
   const CodeBlock: (props: Props) => JSX.Element;
@@ -129,18 +132,6 @@ declare module '@theme/DocPaginator' {
   export default function DocPaginator(props: Props): JSX.Element;
 }
 
-declare module '@theme/DocPaginatorNavLink' {
-  import type {PropNavigationLink} from '@docusaurus/plugin-content-docs';
-
-  // May be simpler to provide a {navigation: PropNavigation} prop?
-  export interface Props {
-    navLink: PropNavigationLink;
-    next?: boolean;
-  }
-
-  export default function DocPaginatorNavLink(props: Props): JSX.Element;
-}
-
 declare module '@theme/DocSidebar' {
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
@@ -160,23 +151,27 @@ declare module '@theme/DocSidebar' {
 declare module '@theme/DocSidebarItem' {
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
-  type DocSidebarPropsBase = {
+  export interface Props {
     readonly activePath: string;
     readonly onItemClick?: (item: PropSidebarItem) => void;
     readonly level: number;
     readonly tabIndex?: number;
-  };
-
-  export interface Props extends DocSidebarPropsBase {
     readonly item: PropSidebarItem;
+    readonly index: number;
   }
-  const DocSidebarItem: (props: Props) => JSX.Element;
-  export default DocSidebarItem;
 
-  export type DocSidebarItemsProps = DocSidebarPropsBase & {
+  export default function DocSidebarItem(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocSidebarItems' {
+  import type {Props as DocSidebarItemProps} from '@theme/DocSidebarItem';
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export type Props = Omit<DocSidebarItemProps, 'item' | 'index'> & {
     readonly items: readonly PropSidebarItem[];
   };
-  export const DocSidebarItems: (props: DocSidebarItemsProps) => JSX.Element;
+
+  export default function DocSidebarItems(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocVersionSuggestions' {
@@ -193,7 +188,7 @@ declare module '@theme/EditThisPage' {
 }
 
 declare module '@theme/ErrorPageContent' {
-  import ErrorComponent from '@theme/Error';
+  import type ErrorComponent from '@theme/Error';
 
   const ErrorPageContent: typeof ErrorComponent;
   export default ErrorPageContent;
@@ -207,99 +202,20 @@ declare module '@theme/Footer' {
 declare module '@theme/Heading' {
   import type {ComponentProps} from 'react';
 
-  export type HeadingType = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-  export interface Props extends ComponentProps<HeadingType> {}
-
-  const Heading: (Tag: HeadingType) => (props: Props) => JSX.Element;
-  export default Heading;
-  export const MainHeading: (props: Props) => JSX.Element;
-}
-
-declare module '@theme/hooks/useHideableNavbar' {
-  export type useHideableNavbarReturns = {
-    readonly navbarRef: (node: HTMLElement | null) => void;
-    readonly isNavbarVisible: boolean;
-  };
-
-  const useHideableNavbar: (hideOnScroll: boolean) => useHideableNavbarReturns;
-  export default useHideableNavbar;
-}
-
-declare module '@theme/hooks/useLockBodyScroll' {
-  const useLockBodyScroll: (lock?: boolean) => void;
-  export default useLockBodyScroll;
-}
-
-declare module '@theme/hooks/usePrismTheme' {
-  import defaultTheme from 'prism-react-renderer/themes/palenight';
-
-  const usePrismTheme: () => typeof defaultTheme;
-  export default usePrismTheme;
-}
-
-declare module '@theme/hooks/useTabGroupChoice' {
-  export type useTabGroupChoiceReturns = {
-    readonly tabGroupChoices: {readonly [groupId: string]: string};
-    readonly setTabGroupChoices: (groupId: string, newChoice: string) => void;
-  };
-
-  const useTabGroupChoice: () => useTabGroupChoiceReturns;
-  export default useTabGroupChoice;
-}
+  type HeadingType = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
-declare module '@theme/hooks/useTheme' {
-  export type useThemeReturns = {
-    readonly isDarkTheme: boolean;
-    readonly setLightTheme: () => void;
-    readonly setDarkTheme: () => void;
-  };
-
-  const useTheme: () => useThemeReturns;
-  export default useTheme;
-}
-
-declare module '@theme/hooks/useThemeContext' {
-  export type ThemeContextProps = {
-    isDarkTheme: boolean;
-    setLightTheme: () => void;
-    setDarkTheme: () => void;
-  };
-
-  export default function useThemeContext(): ThemeContextProps;
-}
-
-declare module '@theme/hooks/useUserPreferencesContext' {
-  export type UserPreferencesContextProps = {
-    tabGroupChoices: {readonly [groupId: string]: string};
-    setTabGroupChoices: (groupId: string, newChoice: string) => void;
-  };
-
-  export default function useUserPreferencesContext(): UserPreferencesContextProps;
-}
-
-declare module '@theme/hooks/useWindowSize' {
-  export const windowSizes: {
-    desktop: 'desktop';
-    mobile: 'mobile';
-    ssr: 'ssr';
-  };
-
-  export type WindowSize = keyof typeof windowSizes;
-
-  export default function useWindowSize(): WindowSize;
-}
-
-declare module '@theme/hooks/useKeyboardNavigation' {
-  const useKeyboardNavigation: () => void;
+  export interface Props extends ComponentProps<HeadingType> {
+    as: HeadingType;
+  }
 
-  export default useKeyboardNavigation;
+  export default function Heading(props: Props): JSX.Element;
 }
 
 declare module '@theme/Layout' {
   import type {ReactNode} from 'react';
 
   export interface Props {
-    readonly children: ReactNode;
+    readonly children?: ReactNode;
     readonly title?: string;
     readonly noFooter?: boolean;
     readonly description?: string;
@@ -314,8 +230,7 @@ declare module '@theme/Layout' {
     };
   }
 
-  const Layout: (props: Props) => JSX.Element;
-  export default Layout;
+  export default function Layout(props: Props): JSX.Element;
 }
 
 declare module '@theme/LayoutHead' {
@@ -323,8 +238,17 @@ declare module '@theme/LayoutHead' {
 
   export interface Props extends Omit<LayoutProps, 'children'> {}
 
-  const LayoutHead: (props: Props) => JSX.Element;
-  export default LayoutHead;
+  export default function LayoutHead(props: Props): JSX.Element;
+}
+
+declare module '@theme/LayoutProviders' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function LayoutProviders(props: Props): JSX.Element;
 }
 
 declare module '@theme/SearchMetadata' {
@@ -383,18 +307,9 @@ declare module '@theme/Navbar' {
 }
 
 declare module '@theme/NavbarItem/DefaultNavbarItem' {
-  import type {ReactNode} from 'react';
-  import type {LinkProps} from '@docusaurus/Link';
-
-  export type NavLinkProps = LinkProps & {
-    readonly activeBasePath?: string;
-    readonly activeBaseRegex?: string;
-    readonly exact?: boolean;
-    readonly label?: ReactNode;
-    readonly prependBaseUrlToHref?: string;
-  };
+  import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
 
-  export type DesktopOrMobileNavBarItemProps = NavLinkProps & {
+  export type DesktopOrMobileNavBarItemProps = NavbarNavLinkProps & {
     readonly isDropdownItem?: boolean;
     readonly className?: string;
     readonly position?: 'left' | 'right';
@@ -404,17 +319,30 @@ declare module '@theme/NavbarItem/DefaultNavbarItem' {
     readonly mobile?: boolean;
   }
 
-  export const NavLink: (props: NavLinkProps) => JSX.Element;
+  export default function DefaultNavbarItem(props: Props): JSX.Element;
+}
+
+declare module '@theme/NavbarItem/NavbarNavLink' {
+  import type {ReactNode} from 'react';
+  import type {LinkProps} from '@docusaurus/Link';
 
-  const DefaultNavbarItem: (props: Props) => JSX.Element;
-  export default DefaultNavbarItem;
+  export type Props = LinkProps & {
+    readonly activeBasePath?: string;
+    readonly activeBaseRegex?: string;
+    readonly exact?: boolean;
+    readonly label?: ReactNode;
+    readonly prependBaseUrlToHref?: string;
+  };
+
+  export default function NavbarNavLink(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DropdownNavbarItem' {
-  import type {NavLinkProps} from '@theme/NavbarItem/DefaultNavbarItem';
+  import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
+
   import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
-  export type DesktopOrMobileNavBarItemProps = NavLinkProps & {
+  export type DesktopOrMobileNavBarItemProps = NavbarNavLinkProps & {
     readonly position?: 'left' | 'right';
     readonly items: readonly LinkLikeNavbarItemProps[];
     readonly className?: string;
@@ -488,10 +416,23 @@ declare module '@theme/NavbarItem/DocNavbarItem' {
   export default DocsSidebarNavbarItem;
 }
 
+declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
+  import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
+
+  export interface Props extends DefaultNavbarItemProps {
+    readonly sidebarId: string;
+    readonly docsPluginId?: string;
+  }
+
+  const DocSidebarNavbarItem: (props: Props) => JSX.Element;
+  export default DocSidebarNavbarItem;
+}
+
 declare module '@theme/NavbarItem' {
   import type {ComponentProps} from 'react';
   import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
   import type {Props as DocNavbarItemProps} from '@theme/NavbarItem/DocNavbarItem';
+  import type {Props as DocSidebarNavbarItemProps} from '@theme/NavbarItem/DocSidebarNavbarItem';
   import type {Props as DocsVersionNavbarItemProps} from '@theme/NavbarItem/DocsVersionNavbarItem';
   import type {Props as DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
   import type {Props as DocsVersionDropdownNavbarItemProps} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
@@ -501,7 +442,8 @@ declare module '@theme/NavbarItem' {
   export type LinkLikeNavbarItemProps =
     | ({readonly type?: 'default'} & DefaultNavbarItemProps)
     | ({readonly type: 'doc'} & DocNavbarItemProps)
-    | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps);
+    | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps)
+    | ({readonly type: 'docSidebar'} & DocSidebarNavbarItemProps);
 
   export type Props = ComponentProps<'a'> & {
     readonly position?: 'left' | 'right';
@@ -523,6 +465,22 @@ declare module '@theme/NavbarItem' {
   export default NavbarItem;
 }
 
+declare module '@theme/NavbarItem/utils' {
+  export function getInfimaActiveClassName(mobile?: boolean): string;
+}
+
+declare module '@theme/PaginatorNavLink' {
+  import type {ReactNode} from 'react';
+  import type {PropNavigationLink} from '@docusaurus/plugin-content-docs';
+
+  export interface Props extends Omit<PropNavigationLink, 'title'> {
+    readonly title: ReactNode;
+    readonly subLabel?: JSX.Element;
+  }
+
+  export default function PaginatorNavLink(props: Props): JSX.Element;
+}
+
 declare module '@theme/SearchBar' {
   export default function SearchBar(): JSX.Element;
 }
@@ -581,23 +539,12 @@ declare module '@theme/ThemedImage' {
 }
 
 declare module '@theme/Details' {
-  import {Details, DetailsProps} from '@docusaurus/theme-common';
+  import {Details, type DetailsProps} from '@docusaurus/theme-common';
 
   export interface Props extends DetailsProps {}
   export default Details;
 }
 
-declare module '@theme/ThemeProvider' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly children: ReactNode;
-  }
-
-  const ThemeProvider: (props: Props) => JSX.Element;
-  export default ThemeProvider;
-}
-
 declare module '@theme/TOCItems' {
   import type {TOCItem} from '@docusaurus/types';
 
@@ -678,46 +625,6 @@ declare module '@theme/Toggle' {
   export default Toggle;
 }
 
-declare module '@theme/UserPreferencesProvider' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly children: ReactNode;
-  }
-
-  const UserPreferencesProvider: (props: Props) => JSX.Element;
-  export default UserPreferencesProvider;
-}
-
-declare module '@theme/LayoutProviders' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly children: ReactNode;
-  }
-
-  const LayoutProviders: (props: Props) => JSX.Element;
-  export default LayoutProviders;
-}
-
-declare module '@theme/ThemeContext' {
-  import type {Context} from 'react';
-  import type {ThemeContextProps} from '@theme/hooks/useThemeContext';
-
-  const ThemeContext: Context<ThemeContextProps | undefined>;
-  export default ThemeContext;
-}
-
-declare module '@theme/UserPreferencesContext' {
-  import type {Context} from 'react';
-  import type {UserPreferencesContextProps} from '@theme/hooks/useUserPreferencesContext';
-
-  const UserPreferencesContext: Context<
-    UserPreferencesContextProps | undefined
-  >;
-  export default UserPreferencesContext;
-}
-
 declare module '@theme/Logo' {
   import type {ComponentProps} from 'react';
 

package/lib/validateThemeConfig.js

@@ -45,6 +45,7 @@ const DEFAULT_CONFIG = {
     items: []
   },
   hideableSidebar: false,
+  autoCollapseSidebarCategories: false,
   tableOfContents: {
     minHeadingLevel: 2,
     maxHeadingLevel: 3
@@ -84,6 +85,11 @@ const DocItemSchema = NavbarItemBaseSchema.append({
   docId: _utilsValidation.Joi.string().required(),
   docsPluginId: _utilsValidation.Joi.string()
 });
+const DocSidebarItemSchema = NavbarItemBaseSchema.append({
+  type: _utilsValidation.Joi.string().equal('docSidebar').required(),
+  sidebarId: _utilsValidation.Joi.string().required(),
+  docsPluginId: _utilsValidation.Joi.string()
+});
 
 const itemWithType = type => {
   // because equal(undefined) is not supported :/
@@ -151,6 +157,9 @@ const NavbarItemSchema = _utilsValidation.Joi.object({
   }, {
     is: itemWithType('doc'),
     then: DocItemSchema
+  }, {
+    is: itemWithType('docSidebar'),
+    then: DocSidebarItemSchema
   }, {
     is: itemWithType('localeDropdown'),
     then: LocaleDropdownNavbarItemSchema
@@ -219,8 +228,10 @@ const ThemeConfigSchema = _utilsValidation.Joi.object({
   image: _utilsValidation.Joi.string(),
   docs: DocsSchema,
   metadata: _utilsValidation.Joi.array().items(HtmlMetadataSchema).default(DEFAULT_CONFIG.metadata),
+  // cSpell:ignore metadatas
   metadatas: _utilsValidation.Joi.any().forbidden().messages({
-    'any.unknown': 'themeConfig.metadatas has been renamed as themeConfig.metadata. See https://github.com/facebook/docusaurus/pull/5871'
+    'any.unknown': // cSpell:ignore metadatas
+    'themeConfig.metadatas has been renamed as themeConfig.metadata. See https://github.com/facebook/docusaurus/pull/5871'
   }),
   announcementBar: _utilsValidation.Joi.object({
     id: _utilsValidation.Joi.string().default('announcement-bar'),
@@ -280,6 +291,7 @@ const ThemeConfigSchema = _utilsValidation.Joi.object({
     additionalLanguages: _utilsValidation.Joi.array().items(_utilsValidation.Joi.string()).default(DEFAULT_CONFIG.prism.additionalLanguages)
   }).default(DEFAULT_CONFIG.prism).unknown(),
   hideableSidebar: _utilsValidation.Joi.bool().default(DEFAULT_CONFIG.hideableSidebar),
+  autoCollapseSidebarCategories: _utilsValidation.Joi.bool().default(DEFAULT_CONFIG.autoCollapseSidebarCategories),
   sidebarCollapsible: _utilsValidation.Joi.forbidden().messages({
     'any.unknown': 'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs'
   }),

package/lib-next/theme/BackToTopButton/styles.module.css

@@ -21,7 +21,7 @@
   transform: scale(0);
 }
 
-.backToTopButton:after {
+.backToTopButton::after {
   content: ' ';
   display: inline-block;
   mask: var(--ifm-menu-link-sublist-icon) 50% / 2rem 2rem no-repeat;

package/lib-next/theme/BlogListPaginator/index.js

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import Link from '@docusaurus/Link';
 import Translate, {translate} from '@docusaurus/Translate';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
 
 function BlogListPaginator(props) {
   const {metadata} = props;
@@ -21,30 +21,30 @@ function BlogListPaginator(props) {
       })}>
       <div className="pagination-nav__item">
         {previousPage && (
-          <Link className="pagination-nav__link" to={previousPage}>
-            <div className="pagination-nav__label">
-              &laquo;{' '}
+          <PaginatorNavLink
+            permalink={previousPage}
+            title={
               <Translate
                 id="theme.blog.paginator.newerEntries"
                 description="The label used to navigate to the newer blog posts page (previous page)">
                 Newer Entries
               </Translate>
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
         {nextPage && (
-          <Link className="pagination-nav__link" to={nextPage}>
-            <div className="pagination-nav__label">
+          <PaginatorNavLink
+            permalink={nextPage}
+            title={
               <Translate
                 id="theme.blog.paginator.olderEntries"
                 description="The label used to navigate to the older blog posts page (next page)">
                 Older Entries
-              </Translate>{' '}
-              &raquo;
-            </div>
-          </Link>
+              </Translate>
+            }
+          />
         )}
       </div>
     </nav>

package/lib-next/theme/BlogPostAuthor/index.js

@@ -19,7 +19,7 @@ function BlogPostAuthor({author}) {
       )}
 
       {
-        // Note: only legacy author frontmatter allow empty name (not frontMatter.authors)
+        // Note: only legacy author front matter allow empty name (not frontMatter.authors)
         name && (
           <div
             className="avatar__intro"

package/lib-next/theme/BlogPostAuthors/index.js

@@ -16,10 +16,20 @@ export default function BlogPostAuthors({authors, assets}) {
     return null;
   }
 
+  const imageOnly = authors.every(({name}) => !name);
   return (
-    <div className="row margin-top--md margin-bottom--sm">
+    <div
+      className={clsx(
+        'margin-top--md margin-bottom--sm',
+        imageOnly ? styles.imageOnlyAuthorRow : 'row',
+      )}>
       {authors.map((author, idx) => (
-        <div className={clsx('col col--6', styles.authorCol)} key={idx}>
+        <div
+          className={clsx(
+            !imageOnly && 'col col--6',
+            imageOnly ? styles.imageOnlyAuthorCol : styles.authorCol,
+          )}
+          key={idx}>
           <BlogPostAuthor
             author={{
               ...author,

package/lib-next/theme/BlogPostAuthors/styles.module.css

@@ -9,3 +9,13 @@
   max-width: inherit !important;
   flex-grow: 1 !important;
 }
+
+.imageOnlyAuthorRow {
+  display: flex;
+  flex-flow: row wrap;
+}
+
+.imageOnlyAuthorCol {
+  margin-left: 0.3rem;
+  margin-right: 0.3rem;
+}