feat(theme): make it possible to provide your own page title formatter (#11090)

Author: slorber

packages/docusaurus-module-type-aliases/src/index.d.ts

@@ -122,6 +122,15 @@ declare module '@theme/Root' {
   export default function Root({children}: Props): ReactNode;
 }
 
+declare module '@theme/ThemeProvider' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+  export default function ThemeProvider({children}: Props): ReactNode;
+}
+
 declare module '@theme/SiteMetadata' {
   import type {ReactNode} from 'react';
 

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/atom.xsl

@@ -1569,6 +1569,17 @@ declare module '@theme/ThemedImage' {
   export default function ThemedImage(props: Props): ReactNode;
 }
 
+declare module '@theme/ThemeProvider/TitleFormatter' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+  export default function ThemeProviderTitleFormatter({
+    children,
+  }: Props): ReactNode;
+}
+
 declare module '@theme/Details' {
   import {Details, type DetailsProps} from '@docusaurus/theme-common/Details';
 

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 ComponentProps, type ReactNode} from 'react';
+import {TitleFormatterProvider} from '@docusaurus/theme-common/internal';
+import type {Props} from '@theme/ThemeProvider/TitleFormatter';
+
+type FormatterProp = ComponentProps<typeof TitleFormatterProvider>['formatter'];
+
+const formatter: FormatterProp = (params) => {
+  // Add your own title formatting logic here!
+  return params.defaultFormatter(params);
+};
+
+export default function ThemeProviderTitleFormatter({
+  children,
+}: Props): ReactNode {
+  return (
+    <TitleFormatterProvider formatter={formatter}>
+      {children}
+    </TitleFormatterProvider>
+  );
+}

packages/docusaurus-theme-classic/src/theme/ThemeProvider/TitleFormatter/index.tsx

@@ -0,0 +1,14 @@
+/**
+ * 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 TitleFormatterProvider from '@theme/ThemeProvider/TitleFormatter';
+import type {Props} from '@theme/ThemeProvider';
+
+export default function ThemeProvider({children}: Props): ReactNode {
+  return <TitleFormatterProvider>{children}</TitleFormatterProvider>;
+}

packages/docusaurus-theme-classic/src/theme/ThemeProvider/index.tsx

@@ -43,7 +43,10 @@ export {
 
 export {DEFAULT_SEARCH_TAG} from './utils/searchUtils';
 
-export {useTitleFormatter} from './utils/generalUtils';
+export {
+  TitleFormatterProvider,
+  useTitleFormatter,
+} from './utils/titleFormatterUtils';
 
 export {useLocationChange} from './utils/useLocationChange';
 

packages/docusaurus-theme-common/src/internal.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 {TitleFormatterFnDefault} from '../titleFormatterUtils';
+
+describe('TitleFormatterFnDefault', () => {
+  it('works', () => {
+    expect(
+      TitleFormatterFnDefault({
+        title: 'a page',
+        siteTitle: 'my site',
+        titleDelimiter: '·',
+      }),
+    ).toBe('a page · my site');
+  });
+
+  it('ignores empty title', () => {
+    expect(
+      TitleFormatterFnDefault({
+        title: '    ',
+        siteTitle: 'my site',
+        titleDelimiter: '·',
+      }),
+    ).toBe('my site');
+  });
+
+  it('does not duplicate site title', () => {
+    // Users may pass <Layout title={siteTitle}> leading to duplicate titles
+    // By default it's preferable to avoid duplicate siteTitle
+    // See also https://github.com/facebook/docusaurus/issues/5878#issuecomment-961505856
+    expect(
+      TitleFormatterFnDefault({
+        title: 'my site',
+        siteTitle: 'my site',
+        titleDelimiter: '·',
+      }),
+    ).toBe('my site');
+  });
+});

packages/docusaurus-theme-common/src/utils/__tests__/generalUtils.test.tsx

@@ -10,7 +10,7 @@ import clsx from 'clsx';
 import Head from '@docusaurus/Head';
 import useRouteContext from '@docusaurus/useRouteContext';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
-import {useTitleFormatter} from './generalUtils';
+import {useTitleFormatter} from './titleFormatterUtils';
 
 type PageMetadataProps = {
   readonly title?: string;
@@ -20,6 +20,55 @@ type PageMetadataProps = {
   readonly children?: ReactNode;
 };
 
+function TitleMetadata({title}: {title: string}) {
+  const titleFormatter = useTitleFormatter();
+  const formattedTitle = titleFormatter.format(title);
+  return (
+    <Head>
+      <title>{formattedTitle}</title>
+      <meta property="og:title" content={formattedTitle} />
+    </Head>
+  );
+}
+
+function DescriptionMetadata({description}: {description: string}) {
+  return (
+    <Head>
+      <meta name="description" content={description} />
+      <meta property="og:description" content={description} />
+    </Head>
+  );
+}
+
+function ImageMetadata({image}: {image: string}) {
+  const {withBaseUrl} = useBaseUrlUtils();
+  const pageImage = withBaseUrl(image, {absolute: true});
+  return (
+    <Head>
+      <meta property="og:image" content={pageImage} />
+      <meta name="twitter:image" content={pageImage} />
+    </Head>
+  );
+}
+
+function KeywordsMetadata({
+  keywords,
+}: {
+  keywords: PageMetadataProps['keywords'];
+}) {
+  return (
+    <Head>
+      <meta
+        name="keywords"
+        content={
+          // https://github.com/microsoft/TypeScript/issues/17002
+          (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
+        }
+      />
+    </Head>
+  );
+}
+
 /**
  * Helper component to manipulate page metadata and override site defaults.
  * Works in the same way as Helmet.
@@ -31,33 +80,14 @@ export function PageMetadata({
   image,
   children,
 }: PageMetadataProps): ReactNode {
-  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={
-            // https://github.com/microsoft/TypeScript/issues/17002
-            (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
-          }
-        />
-      )}
-
-      {pageImage && <meta property="og:image" content={pageImage} />}
-      {pageImage && <meta name="twitter:image" content={pageImage} />}
-
-      {children}
-    </Head>
+    <>
+      {title && <TitleMetadata title={title} />}
+      {description && <DescriptionMetadata description={description} />}
+      {keywords && <KeywordsMetadata keywords={keywords} />}
+      {image && <ImageMetadata image={image} />}
+      {children && <Head>{children}</Head>}
+    </>
   );
 }