feat(v2): useDocusaurusContext().siteMetadata (#3058)

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

@@ -15,6 +15,11 @@ declare module '@generated/docusaurus.config' {
   export default config;
 }
 
+declare module '@generated/site-metadata' {
+  const siteMetadata: any;
+  export default siteMetadata;
+}
+
 declare module '@generated/registry' {
   const registry: {
     readonly [key: string]: [() => Promise<any>, string, string];
@@ -37,29 +42,6 @@ declare module '@generated/routesChunkNames' {
   export default routesChunkNames;
 }
 
-declare module '@generated/site-metadata' {
-  /**
-   * - `type: 'package'`, plugin is in a different package.
-   * - `type: 'project'`, plugin is in the same docusaurus project.
-   * - `type: 'local'`, none of plugin's ancestor directory contains any package.json.
-   * - `type: 'synthetic'`, docusaurus generated internal plugin.
-   */
-  export type PluginVersionInformation =
-    | {readonly type: 'package'; readonly version?: string}
-    | {readonly type: 'project'}
-    | {readonly type: 'local'}
-    | {readonly type: 'synthetic'};
-
-  export type DocusaurusSiteMetadata = {
-    readonly docusaurusVersion: string;
-    readonly siteVersion?: string;
-    readonly pluginVersions: Record<string, PluginVersionInformation>;
-  };
-
-  const siteMetadata: DocusaurusSiteMetadata;
-  export default siteMetadata;
-}
-
 declare module '@theme/*';
 
 declare module '@theme-original/*';

packages/docusaurus-plugin-debug/src/theme/Debug/index.js

@@ -10,11 +10,12 @@ import Layout from '@theme/Layout';
 
 import registry from '@generated/registry';
 import routes from '@generated/routes';
-import siteMetadata from '@generated/site-metadata';
 
 import styles from './styles.module.css';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 function Debug() {
+  const {siteMetadata} = useDocusaurusContext();
   return (
     <Layout permalink="__docusaurus/debug" title="Debug">
       <main className={styles.Container}>

packages/docusaurus-types/src/index.d.ts

@@ -44,9 +44,28 @@ export interface DocusaurusConfig {
   )[];
 }
 
+/**
+ * - `type: 'package'`, plugin is in a different package.
+ * - `type: 'project'`, plugin is in the same docusaurus project.
+ * - `type: 'local'`, none of plugin's ancestor directory contains any package.json.
+ * - `type: 'synthetic'`, docusaurus generated internal plugin.
+ */
+export type DocusaurusPluginVersionInformation =
+  | {readonly type: 'package'; readonly version?: string}
+  | {readonly type: 'project'}
+  | {readonly type: 'local'}
+  | {readonly type: 'synthetic'};
+
+export interface DocusaurusSiteMetadata {
+  readonly docusaurusVersion: string;
+  readonly siteVersion?: string;
+  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;
+}
+
 export interface DocusaurusContext {
-  siteConfig?: DocusaurusConfig;
-  isClient?: boolean;
+  siteConfig: DocusaurusConfig;
+  siteMetadata: DocusaurusSiteMetadata;
+  isClient: boolean;
 }
 
 export interface Preset {

packages/docusaurus/src/client/App.tsx

@@ -9,6 +9,7 @@ import React, {useEffect, useState} from 'react';
 
 import routes from '@generated/routes';
 import siteConfig from '@generated/docusaurus.config';
+import siteMetadata from '@generated/site-metadata';
 import renderRoutes from './exports/renderRoutes';
 import DocusaurusContext from './exports/context';
 import PendingNavigation from './PendingNavigation';
@@ -23,7 +24,7 @@ function App(): JSX.Element {
   }, []);
 
   return (
-    <DocusaurusContext.Provider value={{siteConfig, isClient}}>
+    <DocusaurusContext.Provider value={{siteConfig, siteMetadata, isClient}}>
       <PendingNavigation routes={routes}>
         {renderRoutes(routes)}
       </PendingNavigation>

packages/docusaurus/src/client/exports/context.ts

@@ -8,4 +8,4 @@
 import React from 'react';
 import {DocusaurusContext} from '@docusaurus/types';
 
-export default React.createContext<DocusaurusContext>({});
+export default React.createContext<DocusaurusContext | null>(null);

packages/docusaurus/src/client/exports/useDocusaurusContext.ts

@@ -10,7 +10,12 @@ import context from './context';
 import {DocusaurusContext} from '@docusaurus/types';
 
 function useDocusaurusContext(): DocusaurusContext {
-  return useContext(context);
+  const docusaurusContext = useContext(context);
+  if (docusaurusContext === null) {
+    // should not happen normally
+    throw new Error('Docusaurus context not provided');
+  }
+  return docusaurusContext;
 }
 
 export default useDocusaurusContext;

packages/docusaurus/src/server/index.ts

@@ -6,7 +6,6 @@
  */
 
 import {generate} from '@docusaurus/utils';
-import {DocusaurusSiteMetadata} from '@generated/site-metadata';
 import path, {join} from 'path';
 import {
   BUILD_DIR_NAME,
@@ -22,6 +21,7 @@ import loadRoutes from './routes';
 import loadThemeAlias from './themes';
 import {
   DocusaurusConfig,
+  DocusaurusSiteMetadata,
   LoadContext,
   PluginConfig,
   Props,

packages/docusaurus/src/server/plugins/init.ts

@@ -13,8 +13,8 @@ import {
   Plugin,
   PluginConfig,
   ValidationSchema,
+  DocusaurusPluginVersionInformation,
 } from '@docusaurus/types';
-import {PluginVersionInformation} from '@generated/site-metadata';
 import {CONFIG_FILE_NAME} from '../../constants';
 import {getPluginVersion} from '../versions';
 
@@ -40,7 +40,7 @@ function validateAndStrip<T>(schema: ValidationSchema<T>, options: Partial<T>) {
 }
 
 export type PluginWithVersionInformation = Plugin<unknown> & {
-  readonly version: PluginVersionInformation;
+  readonly version: DocusaurusPluginVersionInformation;
 };
 
 export default function initPlugins({

packages/docusaurus/src/server/versions/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {PluginVersionInformation} from '@generated/site-metadata';
+import {DocusaurusPluginVersionInformation} from '@docusaurus/types';
 import {existsSync, lstatSync} from 'fs-extra';
 import {dirname, join} from 'path';
 
@@ -23,7 +23,7 @@ export function getPackageJsonVersion(
 export function getPluginVersion(
   pluginPath: string,
   siteDir: string,
-): PluginVersionInformation {
+): DocusaurusPluginVersionInformation {
   let potentialPluginPackageJsonDirectory = dirname(pluginPath);
   while (potentialPluginPackageJsonDirectory !== '/') {
     const packageJsonPath = join(

website/docs/configuration.md

@@ -137,8 +137,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 const Hello = () => {
   // highlight-start
-  const context = useDocusaurusContext();
-  const {siteConfig = {}} = context;
+  const {siteConfig} = useDocusaurusContext();
   // highlight-end
   const {title, tagline} = siteConfig;
 

website/docs/docusaurus-core.md

@@ -132,26 +132,42 @@ function MyComponent() {
 
 ### `useDocusaurusContext`
 
-React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](docusaurus.config.js.md).
+React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](docusaurus.config.js.md), and some additional site metadata.
 
 ```ts
+type DocusaurusPluginVersionInformation =
+  | {readonly type: 'package'; readonly version?: string}
+  | {readonly type: 'project'}
+  | {readonly type: 'local'}
+  | {readonly type: 'synthetic'};
+
+interface DocusaurusSiteMetadata {
+  readonly docusaurusVersion: string;
+  readonly siteVersion?: string;
+  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;
+}
+
 interface DocusaurusContext {
-  siteConfig?: DocusaurusConfig;
+  siteConfig: DocusaurusConfig;
+  siteMetadata: DocusaurusSiteMetadata;
 }
 ```
 
 Usage example:
 
-```jsx {2,5}
+```jsx {5,8,9}
 import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
-const Test = () => {
-  const context = useDocusaurusContext();
-  const {siteConfig = {}} = context;
-  const {title} = siteConfig;
-
-  return <h1>{title}</h1>;
+const MyComponent = () => {
+  const {siteConfig, siteMetadata} = useDocusaurusContext();
+  return (
+    <div>
+      <h1>{siteConfig.title}</h1>
+      <div>{siteMetadata.siteVersion}</div>
+      <div>{siteMetadata.docusaurusVersion}</div>
+    </div>
+  );
 };
 ```