@docusaurus/theme-classic 2.0.0-beta.21 → 2.0.0-beta.22

package/lib/theme/BlogTagsPostsPage/index.js

@@ -15,9 +15,9 @@ import {
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import BlogLayout from '@theme/BlogLayout';
-import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';
 import SearchMetadata from '@theme/SearchMetadata';
+import BlogPostItems from '@theme/BlogPostItems';
 // Very simple pluralization: probably good enough for now
 function useBlogPostsPlural() {
   const {selectMessage} = usePluralForm();
@@ -35,9 +35,9 @@ function useBlogPostsPlural() {
       ),
     );
 }
-export default function BlogTagsPostsPage({tag, items, sidebar, listMetadata}) {
+function useBlogTagsPostsPageTitle(tag) {
   const blogPostsPlural = useBlogPostsPlural();
-  const title = translate(
+  return translate(
     {
       id: 'theme.blog.tagTitle',
       description: 'The title of the page for a blog tag',
@@ -45,39 +45,45 @@ export default function BlogTagsPostsPage({tag, items, sidebar, listMetadata}) {
     },
     {nPosts: blogPostsPlural(tag.count), tagName: tag.label},
   );
+}
+function BlogTagsPostsPageMetadata({tag}) {
+  const title = useBlogTagsPostsPageTitle(tag);
+  return (
+    <>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="blog_tags_posts" />
+    </>
+  );
+}
+function BlogTagsPostsPageContent({tag, items, sidebar, listMetadata}) {
+  const title = useBlogTagsPostsPageTitle(tag);
+  return (
+    <BlogLayout sidebar={sidebar}>
+      <header className="margin-bottom--xl">
+        <h1>{title}</h1>
+
+        <Link href={tag.allTagsPath}>
+          <Translate
+            id="theme.tags.tagsPageLink"
+            description="The label of the link targeting the tag list page">
+            View All Tags
+          </Translate>
+        </Link>
+      </header>
+      <BlogPostItems items={items} />
+      <BlogListPaginator metadata={listMetadata} />
+    </BlogLayout>
+  );
+}
+export default function BlogTagsPostsPage(props) {
   return (
     <HtmlClassNameProvider
       className={clsx(
         ThemeClassNames.wrapper.blogPages,
         ThemeClassNames.page.blogTagPostListPage,
       )}>
-      <PageMetadata title={title} />
-      <SearchMetadata tag="blog_tags_posts" />
-      <BlogLayout sidebar={sidebar}>
-        <header className="margin-bottom--xl">
-          <h1>{title}</h1>
-
-          <Link href={tag.allTagsPath}>
-            <Translate
-              id="theme.tags.tagsPageLink"
-              description="The label of the link targeting the tag list page">
-              View All Tags
-            </Translate>
-          </Link>
-        </header>
-
-        {items.map(({content: BlogPostContent}) => (
-          <BlogPostItem
-            key={BlogPostContent.metadata.permalink}
-            frontMatter={BlogPostContent.frontMatter}
-            assets={BlogPostContent.assets}
-            metadata={BlogPostContent.metadata}
-            truncated>
-            <BlogPostContent />
-          </BlogPostItem>
-        ))}
-        <BlogListPaginator metadata={listMetadata} />
-      </BlogLayout>
+      <BlogTagsPostsPageMetadata {...props} />
+      <BlogTagsPostsPageContent {...props} />
     </HtmlClassNameProvider>
   );
 }

package/lib/theme/CodeBlock/Container/index.js

@@ -6,11 +6,8 @@
  */
 import React from 'react';
 import clsx from 'clsx';
-import {
-  usePrismTheme,
-  getPrismCssVariables,
-  ThemeClassNames,
-} from '@docusaurus/theme-common';
+import {ThemeClassNames, usePrismTheme} from '@docusaurus/theme-common';
+import {getPrismCssVariables} from '@docusaurus/theme-common/internal';
 import styles from './styles.module.css';
 export default function CodeBlockContainer({as: As, ...props}) {
   const prismTheme = usePrismTheme();

package/lib/theme/CodeBlock/Content/String.js

@@ -6,15 +6,14 @@
  */
 import React from 'react';
 import clsx from 'clsx';
+import {useThemeConfig, usePrismTheme} from '@docusaurus/theme-common';
 import {
-  useThemeConfig,
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
   containsLineNumbers,
-  usePrismTheme,
   useCodeWordWrap,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import Highlight, {defaultProps} from 'prism-react-renderer';
 import Line from '@theme/CodeBlock/Line';
 import CopyButton from '@theme/CodeBlock/CopyButton';

package/lib/theme/CodeBlock/CopyButton/index.js

@@ -6,6 +6,7 @@
  */
 import React, {useCallback, useState, useRef, useEffect} from 'react';
 import clsx from 'clsx';
+// @ts-expect-error: TODO, we need to make theme-classic have type: module
 import copy from 'copy-text-to-clipboard';
 import {translate} from '@docusaurus/Translate';
 import styles from './styles.module.css';

package/lib/theme/CodeBlock/Line/styles.module.css

@@ -5,13 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-:global(.theme-code-block-highlighted-line) {
-  background-color: var(--docusaurus-highlighted-code-line-bg);
-  display: block;
-  margin: 0 calc(-1 * var(--ifm-pre-padding));
-  padding: 0 var(--ifm-pre-padding);
-}
-
 /* Intentionally has zero specificity, so that to be able to override
 the background in custom CSS file due bug https://github.com/facebook/docusaurus/issues/3678 */
 :where(:root) {
@@ -22,6 +15,13 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   --docusaurus-highlighted-code-line-bg: rgb(100 100 100);
 }
 
+:global(.theme-code-block-highlighted-line) {
+  background-color: var(--docusaurus-highlighted-code-line-bg);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
 .codeLine {
   display: table-row;
   counter-increment: line-count;

package/lib/theme/ColorModeToggle/index.js

@@ -8,8 +8,8 @@ import React from 'react';
 import clsx from 'clsx';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import {translate} from '@docusaurus/Translate';
-import IconLightMode from '@theme/IconLightMode';
-import IconDarkMode from '@theme/IconDarkMode';
+import IconLightMode from '@theme/Icon/LightMode';
+import IconDarkMode from '@theme/Icon/DarkMode';
 import styles from './styles.module.css';
 function ColorModeToggle({className, value, onChange}) {
   const isBrowser = useIsBrowser();

package/lib/theme/DocBreadcrumbs/index.js

@@ -6,15 +6,15 @@
  */
 import React from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
-  ThemeClassNames,
   useSidebarBreadcrumbs,
   useHomePageRoute,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import {translate} from '@docusaurus/Translate';
-import IconHome from '@theme/IconHome';
+import IconHome from '@theme/Icon/Home';
 import styles from './styles.module.css';
 // TODO move to design system folder
 function BreadcrumbsItemLink({children, href, isLast}) {

package/lib/theme/DocCard/index.js

@@ -7,7 +7,10 @@
 import React from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
-import {findFirstCategoryLink, useDocById} from '@docusaurus/theme-common';
+import {
+  findFirstCategoryLink,
+  useDocById,
+} from '@docusaurus/theme-common/internal';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';
 import styles from './styles.module.css';

package/lib/theme/DocCardList/index.js

@@ -6,7 +6,7 @@
  */
 import React from 'react';
 import clsx from 'clsx';
-import {findFirstCategoryLink} from '@docusaurus/theme-common';
+import {findFirstCategoryLink} from '@docusaurus/theme-common/internal';
 import DocCard from '@theme/DocCard';
 // Filter categories that don't have a link.
 function filterItems(items) {
@@ -22,7 +22,7 @@ export default function DocCardList({items, className}) {
     <section className={clsx('row', className)}>
       {filterItems(items).map((item, index) => (
         <article key={index} className="col col--6 margin-bottom--lg">
-          <DocCard key={index} item={item} />
+          <DocCard item={item} />
         </article>
       ))}
     </section>

package/lib/theme/DocItem/Content/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/DocItem/Content';
+export default function DocItemContent({ children }: Props): JSX.Element;

package/lib/theme/DocItem/Content/index.js

@@ -0,0 +1,44 @@
+/**
+ * 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 clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import Heading from '@theme/Heading';
+import MDXContent from '@theme/MDXContent';
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+function useSyntheticTitle() {
+  const {metadata, frontMatter, contentTitle} = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+  if (!shouldRender) {
+    return null;
+  }
+  return metadata.title;
+}
+export default function DocItemContent({children}) {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
+      {syntheticTitle && (
+        <header>
+          <Heading as="h1">{syntheticTitle}</Heading>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/lib/theme/DocItem/Footer/index.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.
+ */
+/// <reference types="react" />
+export default function DocItemFooter(): JSX.Element | null;

package/lib/theme/{DocItemFooter → DocItem/Footer}/index.js

@@ -7,6 +7,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
 import LastUpdated from '@theme/LastUpdated';
 import EditThisPage from '@theme/EditThisPage';
 import TagsListInline from '@theme/TagsListInline';
@@ -46,9 +47,8 @@ function EditMetaRow({
     </div>
   );
 }
-export default function DocItemFooter(props) {
-  const {content: DocContent} = props;
-  const {metadata} = DocContent;
+export default function DocItemFooter() {
+  const {metadata} = useDoc();
   const {editUrl, lastUpdatedAt, formattedLastUpdatedAt, lastUpdatedBy, tags} =
     metadata;
   const canDisplayTagsRow = tags.length > 0;

package/lib/theme/{BlogPostAuthor → DocItem/Layout}/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/BlogPostAuthor';
-export default function BlogPostAuthor({ author }: Props): JSX.Element;
+import type { Props } from '@theme/DocItem/Layout';
+export default function DocItemLayout({ children }: Props): JSX.Element;

package/lib/theme/DocItem/Layout/index.js

@@ -0,0 +1,59 @@
+/**
+ * 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 clsx from 'clsx';
+import {useWindowSize} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import DocItemPaginator from '@theme/DocItem/Paginator';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import DocItemFooter from '@theme/DocItem/Footer';
+import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile';
+import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop';
+import DocItemContent from '@theme/DocItem/Content';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
+import styles from './styles.module.css';
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const {frontMatter, toc} = useDoc();
+  const windowSize = useWindowSize();
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+  const desktop =
+    canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+export default function DocItemLayout({children}) {
+  const docTOC = useDocTOC();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/lib/theme/DocItem/Layout/styles.module.css

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/lib/theme/DocItem/Metadata/index.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.
+ */
+/// <reference types="react" />
+export default function DocItemMetadata(): JSX.Element;

package/lib/theme/DocItem/Metadata/index.js

@@ -0,0 +1,20 @@
+/**
+ * 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 {PageMetadata} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+export default function DocItemMetadata() {
+  const {metadata, frontMatter, assets} = useDoc();
+  return (
+    <PageMetadata
+      title={metadata.title}
+      description={metadata.description}
+      keywords={frontMatter.keywords}
+      image={assets.image ?? frontMatter.image}
+    />
+  );
+}

package/lib/theme/{DocItemFooter → DocItem/Paginator}/index.d.ts

@@ -4,7 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="react" />
-import type { Props } from '@theme/DocItem';
-export default function DocItemFooter(props: Props): JSX.Element | null;
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator(): JSX.Element;

package/lib/theme/DocItem/Paginator/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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 {useDoc} from '@docusaurus/theme-common/internal';
+import DocPaginator from '@theme/DocPaginator';
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator() {
+  const {metadata} = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

package/lib/theme/DocItem/TOC/Desktop/index.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.
+ */
+/// <reference types="react" />
+export default function DocItemTOCDesktop(): JSX.Element;

package/lib/theme/DocItem/TOC/Desktop/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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 {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import TOC from '@theme/TOC';
+export default function DocItemTOCDesktop() {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOC
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocDesktop}
+    />
+  );
+}

package/lib/theme/DocItem/TOC/Mobile/index.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.
+ */
+/// <reference types="react" />
+export default function DocItemTOCMobile(): JSX.Element;

package/lib/theme/DocItem/TOC/Mobile/index.js

@@ -0,0 +1,23 @@
+/**
+ * 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 clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import TOCCollapsible from '@theme/TOCCollapsible';
+import styles from './styles.module.css';
+export default function DocItemTOCMobile() {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOCCollapsible
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={clsx(ThemeClassNames.docs.docTocMobile, styles.tocMobile)}
+    />
+  );
+}

package/lib/theme/DocItem/{styles.module.css → TOC/Mobile/styles.module.css}

@@ -5,16 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docItemContainer header + *,
-.docItemContainer article > *:first-child {
-  margin-top: 0;
-}
-
 @media (min-width: 997px) {
-  .docItemCol {
-    max-width: 75% !important;
-  }
-
   /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
   .tocMobile {
     display: none;