@docusaurus/theme-classic 2.0.0-beta.17 → 2.0.0-beta.18

package/src/theme-classic.d.ts

@@ -41,11 +41,7 @@ declare module '@theme/BlogListPaginator' {
 }
 
 declare module '@theme/BlogSidebar' {
-  export type BlogSidebarItem = {title: string; permalink: string};
-  export type BlogSidebar = {
-    title: string;
-    items: BlogSidebarItem[];
-  };
+  import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     readonly sidebar: BlogSidebar;
@@ -106,7 +102,7 @@ declare module '@theme/BlogPostPaginator' {
 declare module '@theme/BlogLayout' {
   import type {ReactNode} from 'react';
   import type {Props as LayoutProps} from '@theme/Layout';
-  import type {BlogSidebar} from '@theme/BlogSidebar';
+  import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
 
   export interface Props extends LayoutProps {
     readonly sidebar?: BlogSidebar;
@@ -130,6 +126,14 @@ declare module '@theme/CodeBlock' {
   export default function CodeBlock(props: Props): JSX.Element;
 }
 
+declare module '@theme/CodeBlock/CopyButton' {
+  export interface Props {
+    readonly code: string;
+  }
+
+  export default function CopyButton(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocCard' {
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
@@ -180,6 +184,42 @@ declare module '@theme/DocSidebar' {
   export default function DocSidebar(props: Props): JSX.Element;
 }
 
+declare module '@theme/DocSidebar/Mobile' {
+  import type {Props as DocSidebarProps} from '@theme/DocSidebar';
+
+  export interface Props extends DocSidebarProps {}
+
+  export default function DocSidebarMobile(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocSidebar/Desktop' {
+  import type {Props as DocSidebarProps} from '@theme/DocSidebar';
+
+  export interface Props extends DocSidebarProps {}
+
+  export default function DocSidebarDesktop(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocSidebar/Desktop/Content' {
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly className?: string;
+    readonly path: string;
+    readonly sidebar: readonly PropSidebarItem[];
+  }
+
+  export default function Content(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocSidebar/Desktop/CollapseButton' {
+  export interface Props {
+    onClick: React.MouseEventHandler;
+  }
+
+  export default function CollapseButton(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocSidebarItem' {
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
@@ -244,6 +284,77 @@ declare module '@theme/Footer' {
   export default function Footer(): JSX.Element | null;
 }
 
+declare module '@theme/Footer/Logo' {
+  import type {FooterLogo} from '@docusaurus/theme-common';
+
+  export interface Props {
+    logo: FooterLogo;
+  }
+
+  export default function FooterLogo(props: Props): JSX.Element;
+}
+
+declare module '@theme/Footer/Copyright' {
+  export interface Props {
+    copyright: string;
+  }
+
+  export default function FooterCopyright(props: Props): JSX.Element;
+}
+
+declare module '@theme/Footer/LinkItem' {
+  import type {FooterLinkItem} from '@docusaurus/theme-common';
+
+  export interface Props {
+    item: FooterLinkItem;
+  }
+
+  export default function FooterLinkItem(props: Props): JSX.Element;
+}
+
+declare module '@theme/Footer/Layout' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    style: 'light' | 'dark';
+    links: ReactNode;
+    logo: ReactNode;
+    copyright: ReactNode;
+  }
+
+  export default function FooterLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/Footer/Links' {
+  import type {Footer} from '@docusaurus/theme-common';
+
+  export interface Props {
+    links: Footer['links'];
+  }
+
+  export default function FooterLinks(props: Props): JSX.Element;
+}
+
+declare module '@theme/Footer/Links/MultiColumn' {
+  import type {MultiColumnFooter} from '@docusaurus/theme-common';
+
+  export interface Props {
+    columns: MultiColumnFooter['links'];
+  }
+
+  export default function FooterLinksMultiColumn(props: Props): JSX.Element;
+}
+
+declare module '@theme/Footer/Links/Simple' {
+  import type {SimpleFooter} from '@docusaurus/theme-common';
+
+  export interface Props {
+    links: SimpleFooter['links'];
+  }
+
+  export default function FooterLinksSimple(props: Props): JSX.Element;
+}
+
 declare module '@theme/Heading' {
   import type {ComponentProps} from 'react';
 
@@ -261,31 +372,17 @@ declare module '@theme/Layout' {
 
   export interface Props {
     readonly children?: ReactNode;
-    readonly title?: string;
     readonly noFooter?: boolean;
-    readonly description?: string;
-    readonly image?: string;
-    readonly keywords?: string | string[];
-    readonly permalink?: string;
     readonly wrapperClassName?: string;
-    readonly pageClassName?: string;
-    readonly searchMetadata?: {
-      readonly version?: string;
-      readonly tag?: string;
-    };
+
+    // Not really layout-related, but kept for convenience/retro-compatibility
+    readonly title?: string;
+    readonly description?: string;
   }
 
   export default function Layout(props: Props): JSX.Element;
 }
 
-declare module '@theme/LayoutHead' {
-  import type {Props as LayoutProps} from '@theme/Layout';
-
-  export interface Props extends Omit<LayoutProps, 'children'> {}
-
-  export default function LayoutHead(props: Props): JSX.Element;
-}
-
 declare module '@theme/LayoutProviders' {
   import type {ReactNode} from 'react';
 
@@ -320,33 +417,174 @@ declare module '@theme/SkipToContent' {
   export default function SkipToContent(): JSX.Element;
 }
 
-declare module '@theme/MDXComponents' {
+declare module '@theme/MDXComponents/A' {
   import type {ComponentProps} from 'react';
-  import type CodeBlock from '@theme/CodeBlock';
-  import type Head from '@docusaurus/Head';
+
+  export interface Props extends ComponentProps<'a'> {}
+
+  export default function MDXA(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Code' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'code'> {}
+
+  export default function MDXCode(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Details' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'details'> {}
+
+  export default function MDXDetails(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Ul' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'ul'> {}
+
+  export default function MDXUl(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Img' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'img'> {}
+
+  export default function MDXImg(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Head' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'head'> {}
+
+  export default function MDXHead(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Heading' {
+  import type {ComponentProps} from 'react';
+  import type Heading from '@theme/Heading';
+
+  export interface Props extends ComponentProps<typeof Heading> {}
+
+  export default function MDXHeading(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents/Pre' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'pre'> {}
+
+  export default function MDXPre(props: Props): JSX.Element;
+}
+
+declare module '@theme/MDXComponents' {
+  import type {ComponentType, ComponentProps} from 'react';
+
+  import type MDXHead from '@theme/MDXComponents/Head';
+  import type MDXCode from '@theme/MDXComponents/Code';
+  import type MDXA from '@theme/MDXComponents/A';
+  import type MDXPre from '@theme/MDXComponents/Pre';
+  import type MDXDetails from '@theme/MDXComponents/Details';
+  import type MDXUl from '@theme/MDXComponents/Ul';
+  import type MDXImg from '@theme/MDXComponents/Img';
 
   export type MDXComponentsObject = {
-    readonly head: typeof Head;
-    readonly code: typeof CodeBlock;
-    readonly a: (props: ComponentProps<'a'>) => JSX.Element;
-    readonly pre: typeof CodeBlock;
-    readonly details: (props: ComponentProps<'details'>) => JSX.Element;
+    readonly head: typeof MDXHead;
+    readonly code: typeof MDXCode;
+    readonly a: typeof MDXA;
+    readonly pre: typeof MDXPre;
+    readonly details: typeof MDXDetails;
+    readonly ul: typeof MDXUl;
+    readonly img: typeof MDXImg;
     readonly h1: (props: ComponentProps<'h1'>) => JSX.Element;
     readonly h2: (props: ComponentProps<'h2'>) => JSX.Element;
     readonly h3: (props: ComponentProps<'h3'>) => JSX.Element;
     readonly h4: (props: ComponentProps<'h4'>) => JSX.Element;
     readonly h5: (props: ComponentProps<'h5'>) => JSX.Element;
     readonly h6: (props: ComponentProps<'h6'>) => JSX.Element;
-  };
+  } & {[tagName: string]: ComponentType<unknown>};
 
   const MDXComponents: MDXComponentsObject;
   export default MDXComponents;
 }
 
+declare module '@theme/MDXContent' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function MDXContent(props: Props): JSX.Element;
+}
+
 declare module '@theme/Navbar' {
   export default function Navbar(): JSX.Element;
 }
 
+declare module '@theme/Navbar/ColorModeToggle' {
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function NavbarColorModeToggle(
+    props: Props,
+  ): JSX.Element | null;
+}
+
+declare module '@theme/Navbar/Logo' {
+  export default function NavbarLogo(): JSX.Element;
+}
+
+declare module '@theme/Navbar/Content' {
+  export default function NavbarContent(): JSX.Element;
+}
+
+declare module '@theme/Navbar/Layout' {
+  export interface Props {
+    readonly children: React.ReactNode;
+  }
+
+  export default function NavbarLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/Navbar/MobileSidebar' {
+  export default function NavbarMobileSidebar(): JSX.Element;
+}
+
+declare module '@theme/Navbar/MobileSidebar/Layout' {
+  import type {ReactNode} from 'react';
+
+  interface Props {
+    header: ReactNode;
+    primaryMenu: ReactNode;
+    secondaryMenu: ReactNode;
+  }
+
+  export default function NavbarMobileSidebarLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/Navbar/MobileSidebar/Toggle' {
+  export default function NavbarMobileSidebarToggle(): JSX.Element;
+}
+
+declare module '@theme/Navbar/MobileSidebar/PrimaryMenu' {
+  export default function NavbarMobileSidebarPrimaryMenu(): JSX.Element;
+}
+
+declare module '@theme/Navbar/MobileSidebar/SecondaryMenu' {
+  export default function NavbarMobileSidebarSecondaryMenu(): JSX.Element;
+}
+
+declare module '@theme/Navbar/MobileSidebar/Header' {
+  export default function NavbarMobileSidebarHeader(): JSX.Element;
+}
+
 declare module '@theme/NavbarItem/DefaultNavbarItem' {
   import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
 
@@ -530,7 +768,7 @@ declare module '@theme/TabItem' {
     readonly label?: string;
     readonly hidden?: boolean;
     readonly className?: string;
-    readonly attributes?: Record<string, unknown>;
+    readonly attributes?: {[key: string]: unknown};
   }
 
   export default function TabItem(props: Props): JSX.Element;
@@ -548,7 +786,7 @@ declare module '@theme/Tabs' {
     readonly values?: readonly {
       value: string;
       label?: string;
-      attributes?: Record<string, unknown>;
+      attributes?: {[key: string]: unknown};
     }[];
     readonly groupId?: string;
     readonly className?: string;
@@ -633,15 +871,19 @@ declare module '@theme/TOCCollapsible' {
 }
 
 declare module '@theme/ColorModeToggle' {
-  import type {SyntheticEvent} from 'react';
+  import type {ColorMode} from '@docusaurus/theme-common';
 
   export interface Props {
     readonly className?: string;
-    readonly checked: boolean;
-    readonly onChange: (e: SyntheticEvent) => void;
+    readonly value: ColorMode;
+    /**
+     * The parameter represents the "to-be" value. For example, if currently in
+     * dark mode, clicking the button should call `onChange("light")`
+     */
+    readonly onChange: (colorMode: ColorMode) => void;
   }
 
-  export default function Toggle(props: Props): JSX.Element;
+  export default function ColorModeToggle(props: Props): JSX.Element;
 }
 
 declare module '@theme/Logo' {
@@ -720,11 +962,8 @@ declare module '@theme/IconExternalLink' {
 }
 
 declare module '@theme/TagsListByLetter' {
-  export type TagsListItem = Readonly<{
-    name: string;
-    permalink: string;
-    count: number;
-  }>;
+  import type {TagsListItem} from '@docusaurus/theme-common';
+
   export interface Props {
     readonly tags: readonly TagsListItem[];
   }
@@ -732,7 +971,8 @@ declare module '@theme/TagsListByLetter' {
 }
 
 declare module '@theme/TagsListInline' {
-  export type Tag = Readonly<{label: string; permalink: string}>;
+  import type {Tag} from '@docusaurus/utils';
+
   export interface Props {
     readonly tags: readonly Tag[];
   }
@@ -740,7 +980,7 @@ declare module '@theme/TagsListInline' {
 }
 
 declare module '@theme/Tag' {
-  import type {TagsListItem} from '@theme/TagsListByLetter';
+  import type {TagsListItem} from '@docusaurus/theme-common';
   import type {Optional} from 'utility-types';
 
   export interface Props extends Optional<TagsListItem, 'count'> {}
@@ -755,17 +995,3 @@ declare module '@theme/prism-include-languages' {
     PrismObject: typeof PrismNamespace,
   ): void;
 }
-
-declare module '@theme/Seo' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly title?: string;
-    readonly description?: string;
-    readonly keywords?: readonly string[] | string;
-    readonly image?: string;
-    readonly children?: ReactNode;
-  }
-
-  export default function Seo(props: Props): JSX.Element;
-}

package/src/translations.ts

@@ -50,8 +50,11 @@ function getNavbarTranslationFile(navbar: Navbar): TranslationFileContent {
 }
 function translateNavbar(
   navbar: Navbar,
-  navbarTranslations: TranslationFileContent,
+  navbarTranslations: TranslationFileContent | undefined,
 ): Navbar {
+  if (!navbarTranslations) {
+    return navbar;
+  }
   return {
     ...navbar,
     title: navbarTranslations.title?.message ?? navbar.title,
@@ -76,7 +79,7 @@ function translateNavbar(
 function isMultiColumnFooterLinks(
   links: MultiColumnFooter['links'] | SimpleFooter['links'],
 ): links is MultiColumnFooter['links'] {
-  return links.length > 0 && 'title' in links[0];
+  return links.length > 0 && 'title' in links[0]!;
 }
 
 function getFooterTranslationFile(footer: Footer): TranslationFileContent {
@@ -121,8 +124,11 @@ function getFooterTranslationFile(footer: Footer): TranslationFileContent {
 }
 function translateFooter(
   footer: Footer,
-  footerTranslations: TranslationFileContent,
+  footerTranslations: TranslationFileContent | undefined,
 ): Footer {
+  if (!footerTranslations) {
+    return footer;
+  }
   const links = isMultiColumnFooterLinks(footer.links)
     ? footer.links.map((link) => ({
         ...link,
@@ -178,7 +184,7 @@ export function translateThemeConfig({
   themeConfig: ThemeConfig;
   translationFiles: TranslationFile[];
 }): ThemeConfig {
-  const translationFilesMap: Record<string, TranslationFile> = _.keyBy(
+  const translationFilesMap: {[fileName: string]: TranslationFile} = _.keyBy(
     translationFiles,
     (f) => f.path,
   );
@@ -187,10 +193,10 @@ export function translateThemeConfig({
     ...themeConfig,
     navbar: translateNavbar(
       themeConfig.navbar,
-      translationFilesMap.navbar.content,
+      translationFilesMap.navbar?.content,
     ),
     footer: themeConfig.footer
-      ? translateFooter(themeConfig.footer, translationFilesMap.footer.content)
+      ? translateFooter(themeConfig.footer, translationFilesMap.footer?.content)
       : undefined,
   };
 }

package/src/validateThemeConfig.ts

@@ -6,7 +6,10 @@
  */
 
 import {Joi, URISchema} from '@docusaurus/utils-validation';
-import type {ThemeConfig, Validate, ValidationResult} from '@docusaurus/types';
+import type {
+  ThemeConfig,
+  ThemeConfigValidationContext,
+} from '@docusaurus/types';
 
 const DEFAULT_DOCS_CONFIG = {
   versionPersistence: 'localStorage',
@@ -304,7 +307,7 @@ export const ThemeConfigSchema = Joi.object({
     style: Joi.string().equal('dark', 'light').default('light'),
     logo: Joi.object({
       alt: Joi.string().allow(''),
-      src: Joi.string(),
+      src: Joi.string().required(),
       srcDark: Joi.string(),
       // TODO infer this from reading the image
       width: Joi.alternatives().try(Joi.string(), Joi.number()),
@@ -373,9 +376,6 @@ export const ThemeConfigSchema = Joi.object({
 export function validateThemeConfig({
   validate,
   themeConfig,
-}: {
-  validate: Validate<ThemeConfig>;
-  themeConfig: ThemeConfig;
-}): ValidationResult<ThemeConfig> {
+}: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig {
   return validate(ThemeConfigSchema, themeConfig);
 }

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

@@ -1,107 +0,0 @@
-/**
- * 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.
- */
-
-:root {
-  --collapse-button-bg-color-dark: #2e333a;
-}
-
-@media (min-width: 997px) {
-  .sidebar {
-    display: flex;
-    flex-direction: column;
-    max-height: 100vh;
-    height: 100%;
-    position: sticky;
-    top: 0;
-    padding-top: var(--ifm-navbar-height);
-    width: var(--doc-sidebar-width);
-    transition: opacity 50ms ease;
-  }
-
-  .sidebarWithHideableNavbar {
-    padding-top: 0;
-  }
-
-  .sidebarHidden {
-    opacity: 0;
-    height: 0;
-    overflow: hidden;
-    visibility: hidden;
-  }
-
-  .sidebarLogo {
-    display: flex !important;
-    align-items: center;
-    margin: 0 var(--ifm-navbar-padding-horizontal);
-    min-height: var(--ifm-navbar-height);
-    max-height: var(--ifm-navbar-height);
-    color: inherit !important;
-    text-decoration: none !important;
-  }
-
-  .sidebarLogo img {
-    margin-right: 0.5rem;
-    height: 2rem;
-  }
-
-  .menu {
-    flex-grow: 1;
-    padding: 0.5rem;
-  }
-
-  .menuWithAnnouncementBar {
-    margin-bottom: var(--docusaurus-announcement-bar-height);
-  }
-
-  .collapseSidebarButton {
-    display: block !important;
-    background-color: var(--ifm-button-background-color);
-    height: 40px;
-    position: sticky;
-    bottom: 0;
-    border-radius: 0;
-    border: 1px solid var(--ifm-toc-border-color);
-  }
-
-  .collapseSidebarButtonIcon {
-    transform: rotate(180deg);
-    margin-top: 4px;
-  }
-
-  [dir='rtl'] .collapseSidebarButtonIcon {
-    transform: rotate(0);
-  }
-
-  [data-theme='dark'] .collapseSidebarButton {
-    background-color: var(--collapse-button-bg-color-dark);
-  }
-
-  [data-theme='dark'] .collapseSidebarButton:hover,
-  [data-theme='dark'] .collapseSidebarButton:focus {
-    background-color: var(--ifm-color-emphasis-200);
-  }
-}
-
-.sidebarLogo,
-.collapseSidebarButton {
-  display: none;
-}
-
-.sidebarMenuIcon {
-  vertical-align: middle;
-}
-
-.sidebarMenuCloseIcon {
-  display: inline-flex;
-  justify-content: center;
-  align-items: center;
-  height: 24px;
-  font-size: 1.5rem;
-  font-weight: var(--ifm-font-weight-bold);
-  line-height: 0.9;
-  width: 24px;
-}

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

@@ -1,40 +0,0 @@
-/**
- * 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 Head from '@docusaurus/Head';
-import {useTitleFormatter} from '@docusaurus/theme-common';
-import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
-export default function Seo({title, description, keywords, image, children}) {
-  const pageTitle = useTitleFormatter(title);
-  const {withBaseUrl} = useBaseUrlUtils();
-  const pageImage = image
-    ? withBaseUrl(image, {
-        absolute: true,
-      })
-    : undefined;
-  return (
-    <Head>
-      {title && <title>{pageTitle}</title>}
-      {title && <meta property="og:title" content={pageTitle} />}
-
-      {description && <meta name="description" content={description} />}
-      {description && <meta property="og:description" content={description} />}
-
-      {keywords && (
-        <meta
-          name="keywords"
-          content={Array.isArray(keywords) ? keywords.join(',') : keywords}
-        />
-      )}
-
-      {pageImage && <meta property="og:image" content={pageImage} />}
-      {pageImage && <meta name="twitter:image" content={pageImage} />}
-
-      {children}
-    </Head>
-  );
-}