feat: add support for browser-based theme config file (docusaurus.theme.js)

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

@@ -19,6 +19,13 @@ declare module '@generated/docusaurus.config' {
   export default config;
 }
 
+declare module '@generated/docusaurus.theme' {
+  import type {ThemeConfig} from '@docusaurus/types';
+
+  const themeConfig: ThemeConfig;
+  export default themeConfig;
+}
+
 declare module '@generated/site-metadata' {
   import type {SiteMetadata} from '@docusaurus/types';
 

packages/docusaurus-theme-classic/src/theme/AnnouncementBar/Content/index.tsx

@@ -15,14 +15,23 @@ export default function AnnouncementBarContent(
   props: Props,
 ): JSX.Element | null {
   const {announcementBar} = useThemeConfig();
-  const {content} = announcementBar!;
+  const {content: Content} = announcementBar!;
+
+  // TODO Docusaurus v4: remove legacy announcement bar html string form?
+  if (typeof Content === 'string') {
+    return (
+      <div
+        {...props}
+        className={clsx(styles.content, props.className)}
+        // Developer provided the HTML, so assume it's safe.
+        // eslint-disable-next-line react/no-danger
+        dangerouslySetInnerHTML={{__html: Content}}
+      />
+    );
+  }
   return (
-    <div
-      {...props}
-      className={clsx(styles.content, props.className)}
-      // Developer provided the HTML, so assume it's safe.
-      // eslint-disable-next-line react/no-danger
-      dangerouslySetInnerHTML={{__html: content}}
-    />
+    <div {...props} className={clsx(styles.content, props.className)}>
+      <Content />
+    </div>
   );
 }

packages/docusaurus-theme-classic/src/theme/Footer/LinkItem/index.tsx

@@ -14,10 +14,15 @@ import IconExternalLink from '@theme/Icon/ExternalLink';
 import type {Props} from '@theme/Footer/LinkItem';
 
 export default function FooterLinkItem({item}: Props): JSX.Element {
-  const {to, href, label, prependBaseUrlToHref, ...props} = item;
+  const {to, href, label, prependBaseUrlToHref, node, ...props} = item;
   const toUrl = useBaseUrl(to);
   const normalizedHref = useBaseUrl(href, {forcePrependBaseUrl: true});
 
+  if (node) {
+    const NodeElement = node as React.ElementType;
+    return <NodeElement />;
+  }
+
   return (
     <Link
       className="footer__link-item"

packages/docusaurus-theme-classic/src/theme/Footer/Links/Simple/index.tsx

@@ -6,6 +6,7 @@
  */
 
 import React from 'react';
+import {type FooterLinkItem} from '@docusaurus/theme-common';
 import LinkItem from '@theme/Footer/LinkItem';
 import type {Props} from '@theme/Footer/Links/Simple';
 
@@ -30,7 +31,7 @@ export default function FooterLinksSimple({links}: Props): JSX.Element {
   return (
     <div className="footer__links text--center">
       <div className="footer__links">
-        {links.map((item, i) => (
+        {links.map((item: FooterLinkItem, i: number) => (
           <React.Fragment key={i}>
             <SimpleLinkItem item={item} />
             {links.length !== i + 1 && <Separator />}

packages/docusaurus-theme-common/src/utils/useThemeConfig.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type {ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import type {PrismTheme} from 'prism-react-renderer';
 import type {DeepPartial} from 'utility-types';
@@ -51,7 +52,7 @@ export type ColorModeConfig = {
 
 export type AnnouncementBarConfig = {
   id: string;
-  content: string;
+  content: string | ComponentType;
   backgroundColor: string;
   textColor: string;
   isCloseable: boolean;
@@ -99,6 +100,7 @@ export type TableOfContents = {
   maxHeadingLevel: number;
 };
 
+// TODO use TS interface declaration merging?
 // Theme config after validation/normalization
 export type ThemeConfig = {
   docs: {
@@ -129,7 +131,25 @@ export type UserThemeConfig = DeepPartial<ThemeConfig>;
 
 /**
  * A convenient/more semantic way to get theme config from context.
+ * TODO remove old themeConfig in Docusaurus v4?
+ * TODO remove this hook in v4 in favor of a core hook?
  */
 export function useThemeConfig(): ThemeConfig {
-  return useDocusaurusContext().siteConfig.themeConfig as ThemeConfig;
+  const oldThemeConfig = useDocusaurusContext().siteConfig
+    .themeConfig as ThemeConfig;
+  const newThemeConfig = useDocusaurusContext().themeConfig as ThemeConfig;
+
+  // TODO docusaurus-theme-classic/src/options.ts
+  // assigns default values in oldThemeConfig (navbar, footer...)
+  const duplicateKeys = Object.keys(oldThemeConfig).filter((key) =>
+    Object.prototype.hasOwnProperty.call(newThemeConfig, key),
+  );
+
+  if (duplicateKeys.length > 0) {
+    console.warn(
+      `Duplicate keys found in siteConfig.themeConfig and themeConfig: ${duplicateKeys}`,
+    );
+  }
+
+  return {...oldThemeConfig, ...newThemeConfig};
 }

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

@@ -12,6 +12,7 @@ import type {PluginConfig, PresetConfig, HtmlTagObject} from './plugin';
 
 export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';
 
+// TODO use TypeScript interface declaration merging
 export type ThemeConfig = {
   [key: string]: unknown;
 };

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

@@ -4,14 +4,15 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type {DocusaurusConfig} from './config';
+import type {DocusaurusConfig, ThemeConfig} from './config';
 import type {CodeTranslations, I18n} from './i18n';
 import type {LoadedPlugin, PluginVersionInformation} from './plugin';
 import type {RouteConfig} from './routing';
 
 export type DocusaurusContext = {
   siteConfig: DocusaurusConfig;
   siteMetadata: SiteMetadata;
+  themeConfig: ThemeConfig;
   globalData: GlobalData;
   i18n: I18n;
   codeTranslations: CodeTranslations;
@@ -34,6 +35,7 @@ export type LoadContext = {
   generatedFilesDir: string;
   siteConfig: DocusaurusConfig;
   siteConfigPath: string;
+  themeConfigPath: string | undefined; // TODO Docusaurus v4: make it required
   outDir: string;
   /**
    * Directory where all source translations for the current locale can be found

packages/docusaurus-utils/src/constants.ts

@@ -36,6 +36,8 @@ export const DEFAULT_BUILD_DIR_NAME = 'build';
  */
 export const DEFAULT_CONFIG_FILE_NAME = 'docusaurus.config';
 
+export const DEFAULT_THEME_FILE_NAME = 'docusaurus.theme';
+
 /** Can be absolute or relative to site directory. */
 export const BABEL_CONFIG_FILE_NAME =
   process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME ?? 'babel.config.js';

packages/docusaurus-utils/src/index.ts

@@ -11,6 +11,7 @@ export {
   DOCUSAURUS_VERSION,
   DEFAULT_BUILD_DIR_NAME,
   DEFAULT_CONFIG_FILE_NAME,
+  DEFAULT_THEME_FILE_NAME,
   BABEL_CONFIG_FILE_NAME,
   GENERATED_FILES_DIR_NAME,
   SRC_DIR_NAME,

packages/docusaurus/src/client/__tests__/docusaurusContext.test.tsx

@@ -33,6 +33,7 @@ describe('DocusaurusContextProvider', () => {
         "i18n": {},
         "siteConfig": {},
         "siteMetadata": {},
+        "themeConfig": {},
       }
     `);
   });

packages/docusaurus/src/client/docusaurusContext.tsx

@@ -7,6 +7,7 @@
 
 import React, {type ReactNode} from 'react';
 import siteConfig from '@generated/docusaurus.config';
+import themeConfig from '@generated/docusaurus.theme';
 import globalData from '@generated/globalData';
 import i18n from '@generated/i18n';
 import codeTranslations from '@generated/codeTranslations';
@@ -18,6 +19,7 @@ import type {DocusaurusContext} from '@docusaurus/types';
 const contextValue: DocusaurusContext = {
   siteConfig,
   siteMetadata,
+  themeConfig,
   globalData,
   i18n,
   codeTranslations,

packages/docusaurus/src/server/__tests__/__snapshots__/index.test.ts.snap

@@ -125,5 +125,6 @@ exports[`load loads props for site with custom i18n path 1`] = `
     "pluginVersions": {},
     "siteVersion": undefined,
   },
+  "themeConfigPath": undefined,
 }
 `;

packages/docusaurus/src/server/config.ts

@@ -10,13 +10,14 @@ import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
 import {
   DEFAULT_CONFIG_FILE_NAME,
+  DEFAULT_THEME_FILE_NAME,
   findAsyncSequential,
   loadFreshModule,
 } from '@docusaurus/utils';
 import {validateConfig} from './configValidation';
-import type {LoadContext} from '@docusaurus/types';
+import type {DocusaurusConfig, LoadContext} from '@docusaurus/types';
 
-async function findConfig(siteDir: string) {
+async function getConventionalSiteConfigPath(siteDir: string) {
   // We could support .mjs, .ts, etc. in the future
   const candidates = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].map(
     (ext) => DEFAULT_CONFIG_FILE_NAME + ext,
@@ -26,10 +27,10 @@ async function findConfig(siteDir: string) {
     fs.pathExists,
   );
   if (!configPath) {
-    logger.error('No config file found.');
-    logger.info`Expected one of:${candidates}
+    const errorMessage = logger.interpolate`No config file found.
+Expected one of:${candidates}
 You can provide a custom config path with the code=${'--config'} option.`;
-    throw new Error();
+    throw new Error(errorMessage);
   }
   return configPath;
 }
@@ -43,7 +44,7 @@ export async function loadSiteConfig({
 }): Promise<Pick<LoadContext, 'siteConfig' | 'siteConfigPath'>> {
   const siteConfigPath = customConfigFilePath
     ? path.resolve(siteDir, customConfigFilePath)
-    : await findConfig(siteDir);
+    : await getConventionalSiteConfigPath(siteDir);
 
   if (!(await fs.pathExists(siteConfigPath))) {
     throw new Error(`Config file at "${siteConfigPath}" not found.`);
@@ -62,3 +63,50 @@ export async function loadSiteConfig({
   );
   return {siteConfig, siteConfigPath};
 }
+
+async function findConventionalThemeConfigPath(
+  siteDir: string,
+): Promise<string | undefined> {
+  // We could support .mjs, .ts, etc. in the future
+  const candidates = ['.tsx', '.ts', '.jsx', '.js'].map(
+    (ext) => DEFAULT_THEME_FILE_NAME + ext,
+  );
+  const themeConfigPath = await findAsyncSequential(
+    candidates.map((file) => path.join(siteDir, file)),
+    fs.pathExists,
+  );
+
+  return themeConfigPath;
+}
+
+// TODO add tests for this
+export async function findThemeConfigPath(
+  siteDir: string,
+  siteConfig: DocusaurusConfig,
+): Promise<string | undefined> {
+  // TODO add support for custom themeConfig file path
+  // EX: siteConfig.themeConfig: './theme.tsx'
+  // Note: maybe it would be simpler to provide this path through the CLI?
+  if (typeof siteConfig.themeConfig === 'string') {
+    const customThemeConfigPath = siteConfig.themeConfig;
+    if (!(await fs.pathExists(customThemeConfigPath))) {
+      throw new Error(
+        `Theme config file at "${customThemeConfigPath}" not found.`,
+      );
+    }
+    return customThemeConfigPath;
+  }
+  const conventionalThemeConfigPath = await findConventionalThemeConfigPath(
+    siteDir,
+  );
+  // In Docusaurus v3 we require users to provide either the theme config
+  // through the conventional path, or through the legacy siteConfig attribute
+  // To avoid issues we warn users when no theme config is provided at all
+  if (
+    !conventionalThemeConfigPath &&
+    Object.keys(siteConfig.themeConfig ?? {}).length === 0
+  ) {
+    logger.warn`Theme config file couldn't be found at ${DEFAULT_THEME_FILE_NAME}.js or ${DEFAULT_THEME_FILE_NAME}.tsx`;
+  }
+  return conventionalThemeConfigPath;
+}

packages/docusaurus/src/server/index.ts

@@ -13,9 +13,10 @@ import {
   localizePath,
   DEFAULT_BUILD_DIR_NAME,
   DEFAULT_CONFIG_FILE_NAME,
+  DEFAULT_THEME_FILE_NAME,
   GENERATED_FILES_DIR_NAME,
 } from '@docusaurus/utils';
-import {loadSiteConfig} from './config';
+import {findThemeConfigPath, loadSiteConfig} from './config';
 import {loadClientModules} from './clientModules';
 import {loadPlugins} from './plugins';
 import {loadRoutes} from './routes';
@@ -68,6 +69,8 @@ export async function loadContext(
     customConfigFilePath,
   });
 
+  const themeConfigPath = await findThemeConfigPath(siteDir, initialSiteConfig);
+
   const i18n = await loadI18n(initialSiteConfig, {locale});
 
   const baseUrl = localizePath({
@@ -106,6 +109,7 @@ export async function loadContext(
     localizationDir,
     siteConfig,
     siteConfigPath,
+    themeConfigPath,
     outDir,
     baseUrl,
     i18n,
@@ -126,6 +130,7 @@ export async function load(options: LoadContextOptions): Promise<Props> {
     generatedFilesDir,
     siteConfig,
     siteConfigPath,
+    themeConfigPath,
     outDir,
     baseUrl,
     i18n,
@@ -172,6 +177,25 @@ export default ${JSON.stringify(siteConfig, null, 2)};
 `,
   );
 
+  const themeConfigContent = themeConfigPath
+    ? `export {default} from '@site/${path.relative(
+        siteDir,
+        themeConfigPath,
+      )}';`
+    : // TODO Docusaurus v4: require theme config file, remove this fallback
+      `export default {};`;
+  const genThemeConfig = generate(
+    generatedFilesDir,
+    `${DEFAULT_THEME_FILE_NAME}.js`,
+    `/*
+ * AUTOGENERATED - DON'T EDIT
+ * Your edits in this file will be overwritten in the next build!
+ * Modify the docusaurus.config.js file at your site's root instead.
+ */
+${themeConfigContent}
+`,
+  );
+
   const genClientModules = generate(
     generatedFilesDir,
     'client-modules.js',
@@ -236,6 +260,7 @@ ${Object.entries(registry)
     genWarning,
     genClientModules,
     genSiteConfig,
+    genThemeConfig,
     genRegistry,
     genRoutesChunkNames,
     genRoutes,
@@ -248,6 +273,7 @@ ${Object.entries(registry)
   return {
     siteConfig,
     siteConfigPath,
+    themeConfigPath,
     siteMetadata,
     siteDir,
     outDir,