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

package/src/theme/Admonition/index.tsx

@@ -5,102 +5,205 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import Translate from '@docusaurus/Translate';
 import type {Props} from '@theme/Admonition';
 
-const icons = {
-  note: (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="14"
-      height="16"
-      viewBox="0 0 14 16">
+import styles from './styles.module.css';
+
+function NoteIcon() {
+  return (
+    <svg viewBox="0 0 14 16">
       <path
         fillRule="evenodd"
         d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"
       />
     </svg>
-  ),
-  tip: (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="12"
-      height="16"
-      viewBox="0 0 12 16">
+  );
+}
+
+function TipIcon() {
+  return (
+    <svg viewBox="0 0 12 16">
       <path
         fillRule="evenodd"
         d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"
       />
     </svg>
-  ),
-  danger: (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="12"
-      height="16"
-      viewBox="0 0 12 16">
+  );
+}
+
+function DangerIcon() {
+  return (
+    <svg viewBox="0 0 12 16">
       <path
         fillRule="evenodd"
         d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"
       />
     </svg>
-  ),
-  info: (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="14"
-      height="16"
-      viewBox="0 0 14 16">
+  );
+}
+
+function InfoIcon() {
+  return (
+    <svg viewBox="0 0 14 16">
       <path
         fillRule="evenodd"
         d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"
       />
     </svg>
-  ),
-  caution: (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="16"
-      height="16"
-      viewBox="0 0 16 16">
+  );
+}
+
+function CautionIcon() {
+  return (
+    <svg viewBox="0 0 16 16">
       <path
         fillRule="evenodd"
         d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"
       />
     </svg>
-  ),
+  );
+}
+
+type AdmonitionConfig = {
+  iconComponent: React.ComponentType;
+  infimaClassName: string;
+  label: ReactNode;
 };
 
-const ifmClassNames = {
-  note: 'secondary',
-  tip: 'success',
-  danger: 'danger',
-  info: 'info',
-  caution: 'warning',
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+const AdmonitionConfigs: Record<Props['type'], AdmonitionConfig> = {
+  note: {
+    infimaClassName: 'secondary',
+    iconComponent: NoteIcon,
+    label: (
+      <Translate
+        id="theme.admonition.note"
+        description="The default label used for the Note admonition (:::note)">
+        note
+      </Translate>
+    ),
+  },
+  tip: {
+    infimaClassName: 'success',
+    iconComponent: TipIcon,
+    label: (
+      <Translate
+        id="theme.admonition.tip"
+        description="The default label used for the Tip admonition (:::tip)">
+        tip
+      </Translate>
+    ),
+  },
+  danger: {
+    infimaClassName: 'danger',
+    iconComponent: DangerIcon,
+    label: (
+      <Translate
+        id="theme.admonition.danger"
+        description="The default label used for the Danger admonition (:::danger)">
+        danger
+      </Translate>
+    ),
+  },
+  info: {
+    infimaClassName: 'info',
+    iconComponent: InfoIcon,
+    label: (
+      <Translate
+        id="theme.admonition.info"
+        description="The default label used for the Info admonition (:::info)">
+        info
+      </Translate>
+    ),
+  },
+  caution: {
+    infimaClassName: 'warning',
+    iconComponent: CautionIcon,
+    label: (
+      <Translate
+        id="theme.admonition.caution"
+        description="The default label used for the Caution admonition (:::caution)">
+        caution
+      </Translate>
+    ),
+  },
 };
 
-export default function Admonition({
-  children,
-  type,
-  title = type,
-  icon = icons[type],
-}: Props): JSX.Element {
+// Legacy aliases, undocumented but kept for retro-compatibility
+const aliases = {
+  secondary: 'note',
+  important: 'info',
+  success: 'tip',
+  warning: 'danger',
+} as const;
+
+function getAdmonitionConfig(unsafeType: string): AdmonitionConfig {
+  const type =
+    (aliases as {[key: string]: Props['type']})[unsafeType] ?? unsafeType;
+  const config = (AdmonitionConfigs as {[key: string]: AdmonitionConfig})[type];
+  if (config) {
+    return config;
+  }
+  console.warn(
+    `No admonition config found for admonition type "${type}". Using Info as fallback.`,
+  );
+  return AdmonitionConfigs.info;
+}
+
+// Workaround because it's difficult in MDX v1 to provide a MDX title as props
+// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
+function extractMDXAdmonitionTitle(children: ReactNode): {
+  mdxAdmonitionTitle: ReactNode | undefined;
+  rest: ReactNode;
+} {
+  const items = React.Children.toArray(children);
+  const mdxAdmonitionTitle = items.find(
+    (item) =>
+      React.isValidElement(item) &&
+      (item.props as {mdxType: string} | null)?.mdxType ===
+        'mdxAdmonitionTitle',
+  );
+  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>;
+  return {
+    mdxAdmonitionTitle,
+    rest,
+  };
+}
+
+function processAdmonitionProps(props: Props): Props {
+  const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
+  return {
+    ...props,
+    title: props.title ?? mdxAdmonitionTitle,
+    children: rest,
+  };
+}
+
+export default function Admonition(props: Props): JSX.Element {
+  const {children, type, title, icon: iconProp} = processAdmonitionProps(props);
+
+  const typeConfig = getAdmonitionConfig(type);
+  const titleLabel = title ?? typeConfig.label;
+  const {iconComponent: IconComponent} = typeConfig;
+  const icon = iconProp ?? <IconComponent />;
   return (
     <div
       className={clsx(
-        'admonition',
-        `admonition-${type}`,
+        ThemeClassNames.common.admonition,
+        ThemeClassNames.common.admonitionType(props.type),
         'alert',
-        `alert--${ifmClassNames[type]}`,
+        `alert--${typeConfig.infimaClassName}`,
+        styles.admonition,
       )}>
-      <div className="admonition-heading">
-        <h5>
-          <span className="admonition-icon">{icon}</span>
-          {title}
-        </h5>
+      <div className={styles.admonitionHeading}>
+        <span className={styles.admonitionIcon}>{icon}</span>
+        {titleLabel}
       </div>
-      <div className="admonition-content">{children}</div>
+      <div className={styles.admonitionContent}>{children}</div>
     </div>
   );
 }

package/src/{admonitions.css → theme/Admonition/styles.module.css}

@@ -5,35 +5,34 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.admonition h5 {
-  margin-top: 0;
-  margin-bottom: 8px;
+.admonition {
+  margin-bottom: 1em;
+}
+
+.admonitionHeading {
+  font: var(--ifm-heading-font-weight) var(--ifm-h5-font-size) /
+    var(--ifm-heading-line-height) var(--ifm-heading-font-family);
   text-transform: uppercase;
+  margin-bottom: 0.3rem;
 }
 
-.admonition h5 code {
+.admonitionHeading code {
   text-transform: none;
 }
 
-.admonition-icon {
+.admonitionIcon {
   display: inline-block;
   vertical-align: middle;
   margin-right: 0.4em;
 }
 
-.admonition-icon svg {
+.admonitionIcon svg {
   display: inline-block;
-  width: 22px;
-  height: 22px;
-  stroke-width: 0;
+  height: 1.6em;
+  width: 1.6em;
   fill: var(--ifm-alert-foreground-color);
-  stroke: var(--ifm-alert-foreground-color);
 }
 
-.admonition-content > :last-child {
+.admonitionContent > :last-child {
   margin-bottom: 0;
 }
-
-.admonition {
-  margin-bottom: 1em;
-}

package/src/theme/AnnouncementBar/index.tsx

@@ -7,9 +7,10 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useThemeConfig, useAnnouncementBar} from '@docusaurus/theme-common';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import {useAnnouncementBar} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
-import IconClose from '@theme/IconClose';
+import IconClose from '@theme/Icon/Close';
 
 import styles from './styles.module.css';
 

package/src/theme/BackToTopButton/index.tsx

@@ -8,7 +8,8 @@
 import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
-import {ThemeClassNames, useBackToTopButton} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useBackToTopButton} from '@docusaurus/theme-common/internal';
 
 import styles from './styles.module.css';
 

package/src/theme/BlogListPage/index.tsx

@@ -15,10 +15,10 @@ import {
   ThemeClassNames,
 } from '@docusaurus/theme-common';
 import BlogLayout from '@theme/BlogLayout';
-import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';
 import SearchMetadata from '@theme/SearchMetadata';
 import type {Props} from '@theme/BlogListPage';
+import BlogPostItems from '@theme/BlogPostItems';
 
 function BlogListPageMetadata(props: Props): JSX.Element {
   const {metadata} = props;
@@ -40,16 +40,7 @@ function BlogListPageContent(props: Props): JSX.Element {
   const {metadata, items, sidebar} = props;
   return (
     <BlogLayout sidebar={sidebar}>
-      {items.map(({content: BlogPostContent}) => (
-        <BlogPostItem
-          key={BlogPostContent.metadata.permalink}
-          frontMatter={BlogPostContent.frontMatter}
-          assets={BlogPostContent.assets}
-          metadata={BlogPostContent.metadata}
-          truncated={BlogPostContent.metadata.truncated}>
-          <BlogPostContent />
-        </BlogPostItem>
-      ))}
+      <BlogPostItems items={items} />
       <BlogListPaginator metadata={metadata} />
     </BlogLayout>
   );

package/src/theme/BlogPostItem/Container/index.tsx

@@ -0,0 +1,32 @@
+/**
+ * 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 {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import {useBlogPost} from '@docusaurus/theme-common/internal';
+import type {Props} from '@theme/BlogPostItem/Container';
+
+export default function BlogPostItemContainer({
+  children,
+  className,
+}: Props): JSX.Element {
+  const {frontMatter, assets} = useBlogPost();
+  const {withBaseUrl} = useBaseUrlUtils();
+  const image = assets.image ?? frontMatter.image;
+  return (
+    <article
+      className={className}
+      itemProp="blogPost"
+      itemScope
+      itemType="http://schema.org/BlogPosting">
+      {image && (
+        <meta itemProp="image" content={withBaseUrl(image, {absolute: true})} />
+      )}
+      {children}
+    </article>
+  );
+}

package/src/theme/BlogPostItem/Content/index.tsx

@@ -0,0 +1,29 @@
+/**
+ * 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 {blogPostContainerID} from '@docusaurus/utils-common';
+import {useBlogPost} from '@docusaurus/theme-common/internal';
+import MDXContent from '@theme/MDXContent';
+import type {Props} from '@theme/BlogPostItem/Content';
+
+export default function BlogPostItemContent({
+  children,
+  className,
+}: Props): JSX.Element {
+  const {isBlogPostPage} = useBlogPost();
+  return (
+    <div
+      // This ID is used for the feed generation to locate the main content
+      id={isBlogPostPage ? blogPostContainerID : undefined}
+      className={clsx('markdown', className)}
+      itemProp="articleBody">
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/src/theme/BlogPostItem/Footer/ReadMoreLink/index.tsx

@@ -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 Translate, {translate} from '@docusaurus/Translate';
+import Link from '@docusaurus/Link';
+import type {Props} from '@theme/BlogPostItem/Footer/ReadMoreLink';
+
+function ReadMoreLabel() {
+  return (
+    <b>
+      <Translate
+        id="theme.blog.post.readMore"
+        description="The label used in blog post item excerpts to link to full blog posts">
+        Read More
+      </Translate>
+    </b>
+  );
+}
+
+export default function BlogPostItemFooterReadMoreLink(
+  props: Props,
+): JSX.Element {
+  const {blogPostTitle, ...linkProps} = props;
+  return (
+    <Link
+      aria-label={translate(
+        {
+          message: 'Read more about {title}',
+          id: 'theme.blog.post.readMoreLabel',
+          description:
+            'The ARIA label for the link to full blog posts from excerpts',
+        },
+        {title: blogPostTitle},
+      )}
+      {...linkProps}>
+      <ReadMoreLabel />
+    </Link>
+  );
+}

package/src/theme/BlogPostItem/Footer/index.tsx

@@ -0,0 +1,60 @@
+/**
+ * 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 {useBlogPost} from '@docusaurus/theme-common/internal';
+import EditThisPage from '@theme/EditThisPage';
+import TagsListInline from '@theme/TagsListInline';
+import ReadMoreLink from '@theme/BlogPostItem/Footer/ReadMoreLink';
+
+import styles from './styles.module.css';
+
+export default function BlogPostItemFooter(): JSX.Element | null {
+  const {metadata, isBlogPostPage} = useBlogPost();
+  const {tags, title, editUrl, hasTruncateMarker} = metadata;
+
+  // A post is truncated if it's in the "list view" and it has a truncate marker
+  const truncatedPost = !isBlogPostPage && hasTruncateMarker;
+
+  const tagsExists = tags.length > 0;
+
+  const renderFooter = tagsExists || truncatedPost || editUrl;
+
+  if (!renderFooter) {
+    return null;
+  }
+
+  return (
+    <footer
+      className={clsx(
+        'row docusaurus-mt-lg',
+        isBlogPostPage && styles.blogPostFooterDetailsFull,
+      )}>
+      {tagsExists && (
+        <div className={clsx('col', {'col--9': truncatedPost})}>
+          <TagsListInline tags={tags} />
+        </div>
+      )}
+
+      {isBlogPostPage && editUrl && (
+        <div className="col margin-top--sm">
+          <EditThisPage editUrl={editUrl} />
+        </div>
+      )}
+
+      {truncatedPost && (
+        <div
+          className={clsx('col text--right', {
+            'col--3': tagsExists,
+          })}>
+          <ReadMoreLink blogPostTitle={title} to={metadata.permalink} />
+        </div>
+      )}
+    </footer>
+  );
+}

package/src/theme/BlogPostItem/Footer/styles.module.css

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+.blogPostFooterDetailsFull {
+  flex-direction: column;
+}

package/src/theme/{BlogPostAuthor → BlogPostItem/Header/Author}/index.tsx

@@ -6,8 +6,10 @@
  */
 
 import React from 'react';
+import clsx from 'clsx';
 import Link, {type Props as LinkProps} from '@docusaurus/Link';
-import type {Props} from '@theme/BlogPostAuthor';
+
+import type {Props} from '@theme/BlogPostItem/Header/Author';
 
 function MaybeLink(props: LinkProps): JSX.Element {
   if (props.href) {
@@ -16,11 +18,14 @@ function MaybeLink(props: LinkProps): JSX.Element {
   return <>{props.children}</>;
 }
 
-export default function BlogPostAuthor({author}: Props): JSX.Element {
+export default function BlogPostItemHeaderAuthor({
+  author,
+  className,
+}: Props): JSX.Element {
   const {name, title, url, imageURL, email} = author;
   const link = url || (email && `mailto:${email}`) || undefined;
   return (
-    <div className="avatar margin-bottom--sm">
+    <div className={clsx('avatar margin-bottom--sm', className)}>
       {imageURL && (
         <MaybeLink href={link} className="avatar__photo-link">
           <img className="avatar__photo" src={imageURL} alt={name} />

package/{lib/theme/BlogPostAuthors/index.js → src/theme/BlogPostItem/Header/Authors/index.tsx}

@@ -4,12 +4,22 @@
  * 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 BlogPostAuthor from '@theme/BlogPostAuthor';
+import {useBlogPost} from '@docusaurus/theme-common/internal';
+import BlogPostItemHeaderAuthor from '@theme/BlogPostItem/Header/Author';
+import type {Props} from '@theme/BlogPostItem/Header/Authors';
 import styles from './styles.module.css';
+
 // Component responsible for the authors layout
-export default function BlogPostAuthors({authors, assets}) {
+export default function BlogPostItemHeaderAuthors({
+  className,
+}: Props): JSX.Element | null {
+  const {
+    metadata: {authors},
+    assets,
+  } = useBlogPost();
   const authorsCount = authors.length;
   if (authorsCount === 0) {
     return null;
@@ -20,6 +30,7 @@ export default function BlogPostAuthors({authors, assets}) {
       className={clsx(
         'margin-top--md margin-bottom--sm',
         imageOnly ? styles.imageOnlyAuthorRow : 'row',
+        className,
       )}>
       {authors.map((author, idx) => (
         <div
@@ -28,7 +39,7 @@ export default function BlogPostAuthors({authors, assets}) {
             imageOnly ? styles.imageOnlyAuthorCol : styles.authorCol,
           )}
           key={idx}>
-          <BlogPostAuthor
+          <BlogPostItemHeaderAuthor
             author={{
               ...author,
               // Handle author images using relative paths