@docusaurus/theme-classic 3.3.2 → 3.5.0

package/src/index.ts

@@ -10,6 +10,11 @@ import {createRequire} from 'module';
 import rtlcss from 'rtlcss';
 import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
 import {getTranslationFiles, translateThemeConfig} from './translations';
+import {
+  getThemeInlineScript,
+  getAnnouncementBarInlineScript,
+  DataAttributeQueryStringInlineJavaScript,
+} from './inlineScripts';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import type {Plugin as PostCssPlugin} from 'postcss';
@@ -23,97 +28,6 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
   'webpack/lib/ContextReplacementPlugin',
 ) as typeof webpack.ContextReplacementPlugin;
 
-// Need to be inlined to prevent dark mode FOUC
-// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
-const ThemeStorageKey = 'theme';
-// Support for ?docusaurus-theme=dark
-const ThemeQueryStringKey = 'docusaurus-theme';
-// Support for ?docusaurus-data-mode=embed&docusaurus-data-myAttr=42
-const DataQueryStringPrefixKey = 'docusaurus-data-';
-
-const noFlashColorMode = ({
-  defaultMode,
-  respectPrefersColorScheme,
-}: ThemeConfig['colorMode']) =>
-  /* language=js */
-  `(function() {
-  var defaultMode = '${defaultMode}';
-  var respectPrefersColorScheme = ${respectPrefersColorScheme};
-
-  function setDataThemeAttribute(theme) {
-    document.documentElement.setAttribute('data-theme', theme);
-  }
-
-  function getQueryStringTheme() {
-    try {
-      return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
-    } catch(e) {}
-  }
-
-  function getStoredTheme() {
-    try {
-      return localStorage.getItem('${ThemeStorageKey}');
-    } catch (err) {}
-  }
-
-  var initialTheme = getQueryStringTheme() || getStoredTheme();
-  if (initialTheme !== null) {
-    setDataThemeAttribute(initialTheme);
-  } else {
-    if (
-      respectPrefersColorScheme &&
-      window.matchMedia('(prefers-color-scheme: dark)').matches
-    ) {
-      setDataThemeAttribute('dark');
-    } else if (
-      respectPrefersColorScheme &&
-      window.matchMedia('(prefers-color-scheme: light)').matches
-    ) {
-      setDataThemeAttribute('light');
-    } else {
-      setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
-    }
-  }
-})();`;
-
-/* language=js */
-const DataAttributeQueryStringInlineJavaScript = `
-(function() {
-  try {
-    const entries = new URLSearchParams(window.location.search).entries();
-    for (var [searchKey, value] of entries) {
-      if (searchKey.startsWith('${DataQueryStringPrefixKey}')) {
-        var key = searchKey.replace('${DataQueryStringPrefixKey}',"data-")
-        document.documentElement.setAttribute(key, value);
-      }
-    }
-  } catch(e) {}
-})();
-`;
-
-// Duplicated constant. Unfortunately we can't import it from theme-common, as
-// we need to support older nodejs versions without ESM support
-// TODO: import from theme-common once we only support Node.js with ESM support
-// + move all those announcementBar stuff there too
-export const AnnouncementBarDismissStorageKey =
-  'docusaurus.announcement.dismiss';
-const AnnouncementBarDismissDataAttribute =
-  'data-announcement-bar-initially-dismissed';
-// We always render the announcement bar html on the server, to prevent layout
-// shifts on React hydration. The theme can use CSS + the data attribute to hide
-// the announcement bar asap (before React hydration)
-/* language=js */
-const AnnouncementBarInlineJavaScript = `
-(function() {
-  function isDismissed() {
-    try {
-      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
-    } catch (err) {}
-    return false;
-  }
-  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
-})();`;
-
 function getInfimaCSSFile(direction: string) {
   return `infima/dist/css/default/default${
     direction === 'rtl' ? '-rtl' : ''
@@ -126,6 +40,7 @@ export default function themeClassic(
 ): Plugin<undefined> {
   const {
     i18n: {currentLocale, localeConfigs},
+    siteStorage,
   } = context;
   const themeConfig = context.siteConfig.themeConfig as ThemeConfig;
   const {
@@ -218,9 +133,9 @@ export default function themeClassic(
           {
             tagName: 'script',
             innerHTML: `
-${noFlashColorMode(colorMode)}
+${getThemeInlineScript({colorMode, siteStorage})}
 ${DataAttributeQueryStringInlineJavaScript}
-${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+${announcementBar ? getAnnouncementBarInlineScript({siteStorage}) : ''}
             `,
           },
         ],

package/src/inlineScripts.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 type {SiteStorage} from '@docusaurus/types';
+import type {ThemeConfig} from '@docusaurus/theme-common';
+
+// Support for ?docusaurus-theme=dark
+const ThemeQueryStringKey = 'docusaurus-theme';
+
+// Support for ?docusaurus-data-mode=embed&docusaurus-data-myAttr=42
+const DataQueryStringPrefixKey = 'docusaurus-data-';
+
+export function getThemeInlineScript({
+  colorMode: {defaultMode, respectPrefersColorScheme},
+  siteStorage,
+}: {
+  colorMode: ThemeConfig['colorMode'];
+  siteStorage: SiteStorage;
+}): string {
+  // Need to be inlined to prevent dark mode FOUC
+  // Make sure the key is the same as the one in the color mode React context
+  // Currently defined in: `docusaurus-theme-common/src/contexts/colorMode.tsx`
+  const themeStorageKey = `theme${siteStorage.namespace}`;
+
+  /* language=js */
+  return `(function() {
+    var defaultMode = '${defaultMode}';
+    var respectPrefersColorScheme = ${respectPrefersColorScheme};
+
+    function setDataThemeAttribute(theme) {
+      document.documentElement.setAttribute('data-theme', theme);
+    }
+
+    function getQueryStringTheme() {
+      try {
+        return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
+      } catch (e) {
+      }
+    }
+
+    function getStoredTheme() {
+      try {
+        return window['${siteStorage.type}'].getItem('${themeStorageKey}');
+      } catch (err) {
+      }
+    }
+
+    var initialTheme = getQueryStringTheme() || getStoredTheme();
+    if (initialTheme !== null) {
+      setDataThemeAttribute(initialTheme);
+    } else {
+      if (
+        respectPrefersColorScheme &&
+        window.matchMedia('(prefers-color-scheme: dark)').matches
+      ) {
+        setDataThemeAttribute('dark');
+      } else if (
+        respectPrefersColorScheme &&
+        window.matchMedia('(prefers-color-scheme: light)').matches
+      ) {
+        setDataThemeAttribute('light');
+      } else {
+        setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
+      }
+    }
+  })();`;
+}
+
+/* language=js */
+export const DataAttributeQueryStringInlineJavaScript = `
+(function() {
+  try {
+    const entries = new URLSearchParams(window.location.search).entries();
+    for (var [searchKey, value] of entries) {
+      if (searchKey.startsWith('${DataQueryStringPrefixKey}')) {
+        var key = searchKey.replace('${DataQueryStringPrefixKey}',"data-")
+        document.documentElement.setAttribute(key, value);
+      }
+    }
+  } catch(e) {}
+})();
+`;
+
+// We always render the announcement bar html on the server, to prevent layout
+// shifts on React hydration. The theme can use CSS + the data attribute to hide
+// the announcement bar asap (before React hydration)
+export function getAnnouncementBarInlineScript({
+  siteStorage,
+}: {
+  siteStorage: SiteStorage;
+}): string {
+  // Duplicated constant. Unfortunately we can't import it from theme-common, as
+  // we need to support older nodejs versions without ESM support
+  // TODO: import from theme-common once we support Node.js with ESM support
+  // + move all those announcementBar stuff there too
+  const AnnouncementBarDismissStorageKey = `docusaurus.announcement.dismiss${siteStorage.namespace}`;
+  const AnnouncementBarDismissDataAttribute =
+    'data-announcement-bar-initially-dismissed';
+
+  /* language=js */
+  return `(function() {
+  function isDismissed() {
+    try {
+      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
+})();`;
+}

package/src/options.ts

@@ -15,6 +15,7 @@ import type {
 } from '@docusaurus/types';
 
 const defaultPrismTheme = themes.palenight;
+
 const DEFAULT_DOCS_CONFIG: ThemeConfig['docs'] = {
   versionPersistence: 'localStorage',
   sidebar: {
@@ -22,11 +23,12 @@ const DEFAULT_DOCS_CONFIG: ThemeConfig['docs'] = {
     autoCollapseCategories: false,
   },
 };
-const DocsSchema = Joi.object({
+
+const DocsSchema = Joi.object<ThemeConfig['docs']>({
   versionPersistence: Joi.string()
     .equal('localStorage', 'none')
     .default(DEFAULT_DOCS_CONFIG.versionPersistence),
-  sidebar: Joi.object({
+  sidebar: Joi.object<ThemeConfig['docs']['sidebar']>({
     hideable: Joi.bool().default(DEFAULT_DOCS_CONFIG.sidebar.hideable),
     autoCollapseCategories: Joi.bool().default(
       DEFAULT_DOCS_CONFIG.sidebar.autoCollapseCategories,
@@ -34,6 +36,18 @@ const DocsSchema = Joi.object({
   }).default(DEFAULT_DOCS_CONFIG.sidebar),
 }).default(DEFAULT_DOCS_CONFIG);
 
+const DEFAULT_BLOG_CONFIG: ThemeConfig['blog'] = {
+  sidebar: {
+    groupByYear: true,
+  },
+};
+
+const BlogSchema = Joi.object<ThemeConfig['blog']>({
+  sidebar: Joi.object<ThemeConfig['blog']['sidebar']>({
+    groupByYear: Joi.bool().default(DEFAULT_BLOG_CONFIG.sidebar.groupByYear),
+  }).default(DEFAULT_BLOG_CONFIG.sidebar),
+}).default(DEFAULT_BLOG_CONFIG);
+
 const DEFAULT_COLOR_MODE_CONFIG: ThemeConfig['colorMode'] = {
   defaultMode: 'light',
   disableSwitch: false,
@@ -43,6 +57,7 @@ const DEFAULT_COLOR_MODE_CONFIG: ThemeConfig['colorMode'] = {
 export const DEFAULT_CONFIG: ThemeConfig = {
   colorMode: DEFAULT_COLOR_MODE_CONFIG,
   docs: DEFAULT_DOCS_CONFIG,
+  blog: DEFAULT_BLOG_CONFIG,
   metadata: [],
   prism: {
     additionalLanguages: [],
@@ -333,6 +348,7 @@ export const ThemeConfigSchema = Joi.object<ThemeConfig>({
   colorMode: ColorModeSchema,
   image: Joi.string(),
   docs: DocsSchema,
+  blog: BlogSchema,
   metadata: Joi.array()
     .items(HtmlMetadataSchema)
     .default(DEFAULT_CONFIG.metadata),

package/src/theme/Blog/Components/Author/Socials/index.tsx

@@ -0,0 +1,66 @@
+/**
+ * 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 type {ComponentType} from 'react';
+import React from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import type {Props} from '@theme/Blog/Components/Author/Socials';
+
+import Twitter from '@theme/Icon/Socials/Twitter';
+import GitHub from '@theme/Icon/Socials/GitHub';
+import X from '@theme/Icon/Socials/X';
+import StackOverflow from '@theme/Icon/Socials/StackOverflow';
+import LinkedIn from '@theme/Icon/Socials/LinkedIn';
+import DefaultSocialIcon from '@theme/Icon/Socials/Default';
+
+import styles from './styles.module.css';
+
+type SocialIcon = ComponentType<{className: string}>;
+
+type SocialPlatformConfig = {Icon: SocialIcon; label: string};
+
+const SocialPlatformConfigs: Record<string, SocialPlatformConfig> = {
+  twitter: {Icon: Twitter, label: 'Twitter'},
+  github: {Icon: GitHub, label: 'GitHub'},
+  stackoverflow: {Icon: StackOverflow, label: 'Stack Overflow'},
+  linkedin: {Icon: LinkedIn, label: 'LinkedIn'},
+  x: {Icon: X, label: 'X'},
+};
+
+function getSocialPlatformConfig(platformKey: string): SocialPlatformConfig {
+  return (
+    SocialPlatformConfigs[platformKey] ?? {
+      Icon: DefaultSocialIcon,
+      label: platformKey,
+    }
+  );
+}
+
+function SocialLink({platform, link}: {platform: string; link: string}) {
+  const {Icon, label} = getSocialPlatformConfig(platform);
+  return (
+    <Link className={styles.authorSocialLink} href={link} title={label}>
+      <Icon className={clsx(styles.authorSocialLink)} />
+    </Link>
+  );
+}
+
+export default function BlogAuthorSocials({
+  author,
+}: {
+  author: Props['author'];
+}): JSX.Element {
+  const entries = Object.entries(author.socials ?? {});
+  return (
+    <div className={styles.authorSocials}>
+      {entries.map(([platform, linkUrl]) => {
+        return <SocialLink key={platform} platform={platform} link={linkUrl} />;
+      })}
+    </div>
+  );
+}

package/src/theme/Blog/Components/Author/Socials/styles.module.css

@@ -0,0 +1,39 @@
+/**
+ * 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 {
+  --docusaurus-blog-social-icon-size: 1rem;
+}
+
+.authorSocials {
+  /*
+  This ensures that container takes height even if there's no social link
+  This keeps author names aligned even if only some have socials
+   */
+  height: var(--docusaurus-blog-social-icon-size);
+
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  line-height: 0;
+  overflow: hidden;
+  line-clamp: 1;
+  -webkit-line-clamp: 1;
+  -webkit-box-orient: vertical;
+}
+
+.authorSocialLink {
+  height: var(--docusaurus-blog-social-icon-size);
+  width: var(--docusaurus-blog-social-icon-size);
+  line-height: 0;
+  margin-right: 0.4rem;
+}
+
+.authorSocialIcon {
+  width: var(--docusaurus-blog-social-icon-size);
+  height: var(--docusaurus-blog-social-icon-size);
+}

package/src/theme/Blog/Components/Author/index.tsx

@@ -0,0 +1,99 @@
+/**
+ * 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 Link, {type Props as LinkProps} from '@docusaurus/Link';
+import AuthorSocials from '@theme/Blog/Components/Author/Socials';
+import type {Props} from '@theme/Blog/Components/Author';
+import Heading from '@theme/Heading';
+import styles from './styles.module.css';
+
+function MaybeLink(props: LinkProps): JSX.Element {
+  if (props.href) {
+    return <Link {...props} />;
+  }
+  return <>{props.children}</>;
+}
+
+function AuthorTitle({title}: {title: string}) {
+  return (
+    <small className={styles.authorTitle} title={title}>
+      {title}
+    </small>
+  );
+}
+
+function AuthorName({name, as}: {name: string; as: Props['as']}) {
+  if (!as) {
+    return <span className={styles.authorName}>{name}</span>;
+  } else {
+    return (
+      <Heading as={as} className={styles.authorName}>
+        {name}
+      </Heading>
+    );
+  }
+}
+
+function AuthorBlogPostCount({count}: {count: number}) {
+  return <span className={clsx(styles.authorBlogPostCount)}>{count}</span>;
+}
+
+// Note: in the future we might want to have multiple "BlogAuthor" components
+// Creating different display modes with the "as" prop may not be the best idea
+// Explainer: https://kyleshevlin.com/prefer-multiple-compositions/
+// For now, we almost use the same design for all cases, so it's good enough
+export default function BlogAuthor({
+  as,
+  author,
+  className,
+  count,
+}: Props): JSX.Element {
+  const {name, title, url, imageURL, email, page} = author;
+  const link =
+    page?.permalink || url || (email && `mailto:${email}`) || undefined;
+
+  return (
+    <div
+      className={clsx(
+        'avatar margin-bottom--sm',
+        className,
+        styles[`author-as-${as}`],
+      )}>
+      {imageURL && (
+        <MaybeLink href={link} className="avatar__photo-link">
+          <img
+            className={clsx('avatar__photo', styles.authorImage)}
+            src={imageURL}
+            alt={name}
+          />
+        </MaybeLink>
+      )}
+
+      {(name || title) && (
+        <div className={clsx('avatar__intro', styles.authorDetails)}>
+          <div className="avatar__name">
+            {name && (
+              <MaybeLink href={link}>
+                <AuthorName name={name} as={as} />
+              </MaybeLink>
+            )}
+            {count && <AuthorBlogPostCount count={count} />}
+          </div>
+          {!!title && <AuthorTitle title={title} />}
+
+          {/*
+            We always render AuthorSocials even if there's none
+            This keeps other things aligned with flexbox layout
+          */}
+          <AuthorSocials author={author} />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/theme/Blog/Components/Author/styles.module.css

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+
+.authorImage {
+  --ifm-avatar-photo-size: 3.6rem;
+}
+
+.author-as-h1 .authorImage {
+  --ifm-avatar-photo-size: 7rem;
+}
+
+.author-as-h2 .authorImage {
+  --ifm-avatar-photo-size: 5.4rem;
+}
+
+.authorDetails {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: space-around;
+}
+
+.authorName {
+  font-size: 1.1rem;
+  line-height: 1.1rem;
+  display: flex;
+  flex-direction: row;
+}
+
+.author-as-h1 .authorName {
+  font-size: 2.4rem;
+  line-height: 2.4rem;
+  display: inline;
+}
+
+.author-as-h2 .authorName {
+  font-size: 1.4rem;
+  line-height: 1.4rem;
+  display: inline;
+}
+
+.authorTitle {
+  font-size: 0.8rem;
+  line-height: 0.8rem;
+  display: -webkit-box;
+  overflow: hidden;
+  line-clamp: 1;
+  -webkit-line-clamp: 1;
+  -webkit-box-orient: vertical;
+}
+
+.author-as-h1 .authorTitle {
+  font-size: 1.2rem;
+  line-height: 1.2rem;
+}
+
+.author-as-h2 .authorTitle {
+  font-size: 1rem;
+  line-height: 1rem;
+}
+
+.authorBlogPostCount {
+  background: var(--ifm-color-secondary);
+  color: var(--ifm-color-black);
+  font-size: 0.8rem;
+  line-height: 1.2;
+  border-radius: var(--ifm-global-radius);
+  padding: 0.1rem 0.4rem;
+  margin-left: 0.3rem;
+}

package/src/theme/Blog/Pages/BlogAuthorsListPage/index.tsx

@@ -0,0 +1,62 @@
+/**
+ * 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, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
+import {translateBlogAuthorsListPageTitle} from '@docusaurus/theme-common/internal';
+import BlogLayout from '@theme/BlogLayout';
+import type {Props} from '@theme/Blog/Pages/BlogAuthorsListPage';
+import SearchMetadata from '@theme/SearchMetadata';
+import Heading from '@theme/Heading';
+import Author from '@theme/Blog/Components/Author';
+import type {AuthorItemProp} from '@docusaurus/plugin-content-blog';
+import styles from './styles.module.css';
+
+function AuthorListItem({author}: {author: AuthorItemProp}) {
+  return (
+    <li className={styles.authorListItem}>
+      <Author as="h2" author={author} count={author.count} />
+    </li>
+  );
+}
+
+function AuthorsList({authors}: {authors: Props['authors']}) {
+  return (
+    <section className={clsx('margin-vert--lg', styles.authorsListSection)}>
+      <ul>
+        {authors.map((author) => (
+          <AuthorListItem key={author.key} author={author} />
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+export default function BlogAuthorsListPage({
+  authors,
+  sidebar,
+}: Props): ReactNode {
+  const title: string = translateBlogAuthorsListPageTitle();
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.blogPages,
+        ThemeClassNames.page.blogAuthorsListPage,
+      )}>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="blog_authors_list" />
+      <BlogLayout sidebar={sidebar}>
+        <Heading as="h1">{title}</Heading>
+        <AuthorsList authors={authors} />
+      </BlogLayout>
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/Blog/Pages/BlogAuthorsListPage/styles.module.css

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+.authorListItem {
+  list-style-type: none;
+  margin-bottom: 2rem;
+}