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

package/src/theme/BlogPostItem/index.tsx

@@ -12,6 +12,7 @@ import Translate, {translate} from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import {usePluralForm} from '@docusaurus/theme-common';
+import {blogPostContainerID} from '@docusaurus/utils-common';
 import MDXComponents from '@theme/MDXComponents';
 import EditThisPage from '@theme/EditThisPage';
 import type {Props} from '@theme/BlogPostItem';
@@ -65,11 +66,14 @@ function BlogPostItem(props: Props): JSX.Element {
   const image = assets.image ?? frontMatter.image;
   const truncatedPost = !isBlogPostPage && truncated;
   const tagsExists = tags.length > 0;
+  const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
 
-  const renderPostHeader = () => {
-    const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
-
-    return (
+  return (
+    <article
+      className={!isBlogPostPage ? 'margin-bottom--xl' : undefined}
+      itemProp="blogPost"
+      itemScope
+      itemType="http://schema.org/BlogPosting">
       <header>
         <TitleHeading className={styles.blogPostTitle} itemProp="headline">
           {isBlogPostPage ? (
@@ -94,22 +98,16 @@ function BlogPostItem(props: Props): JSX.Element {
         </div>
         <BlogPostAuthors authors={authors} assets={assets} />
       </header>
-    );
-  };
-
-  return (
-    <article
-      className={!isBlogPostPage ? 'margin-bottom--xl' : undefined}
-      itemProp="blogPost"
-      itemScope
-      itemType="http://schema.org/BlogPosting">
-      {renderPostHeader()}
 
       {image && (
         <meta itemProp="image" content={withBaseUrl(image, {absolute: true})} />
       )}
 
-      <div className="markdown" itemProp="articleBody">
+      <div
+        // This ID is used for the feed generation to locate the main content
+        id={isBlogPostPage ? blogPostContainerID : undefined}
+        className="markdown"
+        itemProp="articleBody">
         <MDXProvider components={MDXComponents}>{children}</MDXProvider>
       </div>
 

package/src/theme/BlogPostPage/index.tsx

@@ -16,14 +16,17 @@ import TOC from '@theme/TOC';
 
 function BlogPostPage(props: Props): JSX.Element {
   const {content: BlogPostContents, sidebar} = props;
+  const {assets, metadata} = BlogPostContents;
   const {
-    // TODO this frontmatter is not validated/normalized, it's the raw user-provided one. We should expose normalized one too!
+    title,
+    description,
+    nextItem,
+    prevItem,
+    date,
+    tags,
+    authors,
     frontMatter,
-    assets,
-    metadata,
-  } = BlogPostContents;
-  const {title, description, nextItem, prevItem, date, tags, authors} =
-    metadata;
+  } = metadata;
   const {
     hide_table_of_contents: hideTableOfContents,
     keywords,
@@ -59,7 +62,7 @@ function BlogPostPage(props: Props): JSX.Element {
         <meta property="og:type" content="article" />
         <meta property="article:published_time" content={date} />
 
-        {/* TODO double check those article metas array syntaxes, see https://ogp.me/#array */}
+        {/* TODO double check those article meta array syntaxes, see https://ogp.me/#array */}
         {authors.some((author) => author.url) && (
           <meta
             property="article:author"

package/src/theme/BlogPostPaginator/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import Translate, {translate} from '@docusaurus/Translate';
-import Link from '@docusaurus/Link';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/BlogPostPaginator';
 
 function BlogPostPaginator(props: Props): JSX.Element {
@@ -23,34 +23,30 @@ function BlogPostPaginator(props: Props): JSX.Element {
       })}>
       <div className="pagination-nav__item">
         {prevItem && (
-          <Link className="pagination-nav__link" to={prevItem.permalink}>
-            <div className="pagination-nav__sublabel">
+          <PaginatorNavLink
+            {...prevItem}
+            subLabel={
               <Translate
                 id="theme.blog.post.paginator.newerPost"
                 description="The blog post button label to navigate to the newer/previous post">
                 Newer Post
               </Translate>
-            </div>
-            <div className="pagination-nav__label">
-              &laquo; {prevItem.title}
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
         {nextItem && (
-          <Link className="pagination-nav__link" to={nextItem.permalink}>
-            <div className="pagination-nav__sublabel">
+          <PaginatorNavLink
+            {...nextItem}
+            subLabel={
               <Translate
                 id="theme.blog.post.paginator.olderPost"
                 description="The blog post button label to navigate to the older/next post">
                 Older Post
               </Translate>
-            </div>
-            <div className="pagination-nav__label">
-              {nextItem.title} &raquo;
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
     </nav>

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

@@ -30,9 +30,11 @@
 .sidebarItemLink {
   color: var(--ifm-font-color-base);
 }
+
 .sidebarItemLink:hover {
   text-decoration: none;
 }
+
 .sidebarItemLinkActive {
   color: var(--ifm-color-primary) !important;
 }

package/src/theme/CodeBlock/index.tsx

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useEffect, useState} from 'react';
+import React, {isValidElement, useEffect, useState} from 'react';
 import clsx from 'clsx';
-import Highlight, {defaultProps, Language} from 'prism-react-renderer';
+import Highlight, {defaultProps, type Language} from 'prism-react-renderer';
 import copy from 'copy-text-to-clipboard';
 import Translate, {translate} from '@docusaurus/Translate';
 import {
@@ -16,17 +16,18 @@ import {
   parseLanguage,
   parseLines,
   ThemeClassNames,
+  usePrismTheme,
 } from '@docusaurus/theme-common';
-import usePrismTheme from '@theme/hooks/usePrismTheme';
 import type {Props} from '@theme/CodeBlock';
 
 import styles from './styles.module.css';
 
 export default function CodeBlock({
   children,
-  className: blockClassName,
+  className: blockClassName = '',
   metastring,
   title,
+  language: languageProp,
 }: Props): JSX.Element {
   const {prism} = useThemeConfig();
 
@@ -43,19 +44,49 @@ export default function CodeBlock({
     setMounted(true);
   }, []);
 
-  // TODO: the title is provided by MDX as props automatically
-  // so we probably don't need to parse the metastring
-  // (note: title="xyz" => title prop still has the quotes)
+  // We still parse the metastring in case we want to support more syntax in the
+  // future. Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
   const codeBlockTitle = parseCodeBlockTitle(metastring) || title;
   const prismTheme = usePrismTheme();
 
-  // In case interleaved Markdown (e.g. when using CodeBlock as standalone component).
+  // <pre> tags in markdown map to CodeBlocks and they may contain JSX children.
+  // When the children is not a simple string, we just return a styled block without actually highlighting.
+  if (React.Children.toArray(children).some((el) => isValidElement(el))) {
+    return (
+      <Highlight
+        {...defaultProps}
+        key={String(mounted)}
+        theme={prismTheme}
+        code=""
+        language={'text' as Language}>
+        {({className, style}) => (
+          <pre
+            /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
+            tabIndex={0}
+            className={clsx(
+              className,
+              styles.codeBlockStandalone,
+              'thin-scrollbar',
+              styles.codeBlockContainer,
+              blockClassName,
+              ThemeClassNames.common.codeBlock,
+            )}
+            style={style}>
+            <code className={styles.codeBlockLines}>{children}</code>
+          </pre>
+        )}
+      </Highlight>
+    );
+  }
+
+  // The children is now guaranteed to be one/more plain strings
   const content = Array.isArray(children)
     ? children.join('')
     : (children as string);
 
   const language =
-    parseLanguage(blockClassName) ?? (prism.defaultLanguage as Language);
+    languageProp ?? parseLanguage(blockClassName) ?? prism.defaultLanguage;
   const {highlightLines, code} = parseLines(content, metastring, language);
 
   const handleCopyCode = () => {
@@ -71,12 +102,16 @@ export default function CodeBlock({
       key={String(mounted)}
       theme={prismTheme}
       code={code}
-      language={language}>
+      language={(language ?? 'text') as Language}>
       {({className, style, tokens, getLineProps, getTokenProps}) => (
         <div
           className={clsx(
             styles.codeBlockContainer,
             blockClassName,
+            {
+              [`language-${language}`]:
+                language && !blockClassName.includes(`language-${language}`),
+            },
             ThemeClassNames.common.codeBlock,
           )}>
           {codeBlockTitle && (

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

@@ -13,7 +13,7 @@
 
 .codeBlockContent {
   position: relative;
-  /*rtl:ignore*/
+  /* rtl:ignore */
   direction: ltr;
 }
 
@@ -26,19 +26,24 @@
   border-top-right-radius: var(--ifm-global-radius);
 }
 
+.codeBlock {
+  margin: 0;
+  padding: 0;
+  border-radius: var(--ifm-global-radius);
+}
+
 .codeBlockTitle + .codeBlockContent .codeBlock {
   border-top-left-radius: 0;
   border-top-right-radius: 0;
 }
 
-.codeBlock {
-  margin: 0;
+.codeBlockStandalone {
   padding: 0;
   border-radius: var(--ifm-global-radius);
 }
 
 .copyButton {
-  background: rgba(0, 0, 0, 0.3);
+  background: rgb(0 0 0 / 30%);
   border-radius: var(--ifm-global-radius);
   color: var(--ifm-color-white);
   opacity: 0;
@@ -50,15 +55,15 @@
   transition: opacity 200ms ease-in-out;
 }
 
-.codeBlockTitle:hover + .codeBlockContent .copyButton,
+.copyButton:focus,
 .codeBlockContent:hover > .copyButton,
-.copyButton:focus {
+.codeBlockTitle:hover + .codeBlockContent .copyButton {
   opacity: 1;
 }
 
 .codeBlockLines {
   font: inherit;
-  /*rtl:ignore*/
+  /* rtl:ignore */
   float: left;
   min-width: 100%;
   padding: var(--ifm-pre-padding);

package/src/theme/DocCard/index.tsx

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ReactNode} from 'react';
+import React, {type ReactNode} from 'react';
 import Link from '@docusaurus/Link';
-import {
+import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
 } from '@docusaurus/plugin-content-docs';

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

@@ -7,14 +7,13 @@
 
 .cardContainer {
   height: 8rem;
-
   color: var(--ifm-color-emphasis-800);
   --ifm-link-color: var(--ifm-color-emphasis-800);
   --ifm-link-hover-color: var(--ifm-color-emphasis-800);
   --ifm-link-hover-decoration: none;
 
   /* box-shadow: var(--ifm-global-shadow-lw); */
-  box-shadow: 0 1.5px 3px 0 rgba(0, 0, 0, 0.15);
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
   border: 1px solid var(--ifm-color-emphasis-200);
   transition: box-shadow var(--ifm-transition-fast) ease,
     background-color var(--ifm-transition-fast) ease;
@@ -22,8 +21,9 @@
 
 .cardContainer.cardContainerLink:hover {
   /* box-shadow: var(--ifm-global-shadow-md); */
-  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2);
+  box-shadow: 0 4px 8px 0 rgb(0 0 0 / 20%);
 }
+
 html[data-theme='dark'] .cardContainer.cardContainerLink:hover {
   --ifm-card-background-color: #2d2d2d; /* original, non-hovered color is #242526 */
 }

package/src/theme/DocCardList/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 
 import DocCard from '@theme/DocCard';
-import {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
 export default function DocCardList({
   items,

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -13,7 +13,8 @@ import DocPaginator from '@theme/DocPaginator';
 import Seo from '@theme/Seo';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';
-import {MainHeading} from '@theme/Heading';
+import Heading from '@theme/Heading';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 
 import styles from './styles.module.css';
 
@@ -26,14 +27,17 @@ export default function DocCategoryGeneratedIndexPage({
       <Seo
         title={categoryGeneratedIndex.title}
         description={categoryGeneratedIndex.description}
+        keywords={categoryGeneratedIndex.keywords}
+        // TODO `require` this?
+        image={useBaseUrl(categoryGeneratedIndex.image)}
       />
       <div className={styles.generatedIndexPage}>
         <DocVersionBanner />
         <DocVersionBadge />
         <header>
-          <MainHeading className={styles.title}>
+          <Heading as="h1" className={styles.title}>
             {categoryGeneratedIndex.title}
-          </MainHeading>
+          </Heading>
           {categoryGeneratedIndex.description && (
             <p>{categoryGeneratedIndex.description}</p>
           )}

package/src/theme/DocItem/index.tsx

@@ -7,7 +7,6 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import useWindowSize from '@theme/hooks/useWindowSize';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';
@@ -16,9 +15,9 @@ import type {Props} from '@theme/DocItem';
 import DocItemFooter from '@theme/DocItemFooter';
 import TOC from '@theme/TOC';
 import TOCCollapsible from '@theme/TOCCollapsible';
-import {MainHeading} from '@theme/Heading';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {ThemeClassNames, useWindowSize} from '@docusaurus/theme-common';
 
 export default function DocItem(props: Props): JSX.Element {
   const {content: DocContent} = props;
@@ -34,7 +33,7 @@ export default function DocItem(props: Props): JSX.Element {
   const {description, title} = metadata;
 
   // We only add a title if:
-  // - user asks to hide it with frontmatter
+  // - user asks to hide it with front matter
   // - the markdown content does not already contain a top-level h1 heading
   const shouldAddTitle =
     !hideTitle && typeof DocContent.contentTitle === 'undefined';
@@ -76,11 +75,15 @@ export default function DocItem(props: Props): JSX.Element {
               <div
                 className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
                 {/*
-                Title can be declared inside md content or declared through frontmatter and added manually
+                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
                 */}
-                {shouldAddTitle && <MainHeading>{title}</MainHeading>}
+                {shouldAddTitle && (
+                  <header>
+                    <Heading as="h1">{title}</Heading>
+                  </header>
+                )}
 
                 <DocContent />
               </div>

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

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docItemContainer article > *:first-child,
-.docItemContainer header + * {
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
   margin-top: 0;
 }
 

package/src/theme/DocItemFooter/index.tsx

@@ -12,7 +12,7 @@ import LastUpdated from '@theme/LastUpdated';
 import type {Props} from '@theme/DocItem';
 import EditThisPage from '@theme/EditThisPage';
 import TagsListInline, {
-  Props as TagsListInlineProps,
+  type Props as TagsListInlineProps,
 } from '@theme/TagsListInline';
 
 import styles from './styles.module.css';

package/src/theme/DocPage/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ReactNode, useState, useCallback} from 'react';
+import React, {type ReactNode, useState, useCallback} from 'react';
 import {MDXProvider} from '@mdx-js/react';
 
 import renderRoutes from '@docusaurus/renderRoutes';
@@ -70,9 +70,13 @@ function DocPageContent({
 
         {sidebar && (
           <aside
-            className={clsx(styles.docSidebarContainer, {
-              [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
-            })}
+            className={clsx(
+              ThemeClassNames.docs.docSidebarContainer,
+              styles.docSidebarContainer,
+              {
+                [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
+              },
+            )}
             onTransitionEnd={(e) => {
               if (
                 !e.currentTarget.classList.contains(styles.docSidebarContainer)

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

@@ -68,6 +68,7 @@
   .expandSidebarButtonIcon {
     transform: rotate(0);
   }
+
   html[dir='rtl'] .expandSidebarButtonIcon {
     transform: rotate(180deg);
   }

package/src/theme/DocPaginator/index.tsx

@@ -6,8 +6,8 @@
  */
 
 import React from 'react';
-import {translate} from '@docusaurus/Translate';
-import DocPaginatorNavLink from '@theme/DocPaginatorNavLink';
+import Translate, {translate} from '@docusaurus/Translate';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/DocPaginator';
 
 function DocPaginator(props: Props): JSX.Element {
@@ -22,10 +22,32 @@ function DocPaginator(props: Props): JSX.Element {
         description: 'The ARIA label for the docs pagination',
       })}>
       <div className="pagination-nav__item">
-        {previous && <DocPaginatorNavLink navLink={previous} />}
+        {previous && (
+          <PaginatorNavLink
+            {...previous}
+            subLabel={
+              <Translate
+                id="theme.docs.paginator.previous"
+                description="The label used to navigate to the previous doc">
+                Previous
+              </Translate>
+            }
+          />
+        )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
-        {next && <DocPaginatorNavLink navLink={next} next />}
+        {next && (
+          <PaginatorNavLink
+            {...next}
+            subLabel={
+              <Translate
+                id="theme.docs.paginator.next"
+                description="The label used to navigate to the next doc">
+                Next
+              </Translate>
+            }
+          />
+        )}
       </div>
     </nav>
   );

package/src/theme/DocSidebar/index.tsx

@@ -11,15 +11,15 @@ import {
   useThemeConfig,
   useAnnouncementBar,
   MobileSecondaryMenuFiller,
-  MobileSecondaryMenuComponent,
+  type MobileSecondaryMenuComponent,
   ThemeClassNames,
   useScrollPosition,
+  useWindowSize,
 } from '@docusaurus/theme-common';
-import useWindowSize from '@theme/hooks/useWindowSize';
 import Logo from '@theme/Logo';
 import IconArrow from '@theme/IconArrow';
 import {translate} from '@docusaurus/Translate';
-import {DocSidebarItems} from '@theme/DocSidebarItem';
+import DocSidebarItems from '@theme/DocSidebarItems';
 import type {Props} from '@theme/DocSidebar';
 
 import styles from './styles.module.css';

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

@@ -71,6 +71,7 @@
     transform: rotate(180deg);
     margin-top: 4px;
   }
+
   html[dir='rtl'] .collapseSidebarButtonIcon {
     transform: rotate(0);
   }