@docusaurus/core 2.0.0-beta.16 → 2.0.0-beta.19

package/bin/beforeCli.mjs

@@ -14,15 +14,21 @@ import path from 'path';
 import updateNotifier from 'update-notifier';
 import boxen from 'boxen';
 import {createRequire} from 'module';
+import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
 
 const packageJson = createRequire(import.meta.url)('../package.json');
-const sitePkg = createRequire(path.join(process.cwd(), 'package.json'))(
-  './package.json',
-);
+/** @type {Record<string, any>} */
+let sitePkg;
+try {
+  sitePkg = createRequire(path.resolve('package.json'))('./package.json');
+} catch {
+  logger.warn`path=${'package.json'} file not found at CWD: path=${process.cwd()}.`;
+  logger.info`This is non-critical, but could lead to undesired behavior downstream. Docusaurus assumes that path=${'package.json'} exists at CWD, because it's where the package manager looks up the script at. A common reason is because you have changed directory in the script. Instead of writing code=${'"start": "cd website && docusaurus start"'}, consider using the code=${'[siteDir]'} argument: code=${'"start": "docusaurus start website"'}.`;
+  sitePkg = {};
+}
 
 const {
   name,
-  version,
   engines: {node: requiredVersion},
 } = packageJson;
 
@@ -40,12 +46,11 @@ export default async function beforeCli() {
   const notifier = updateNotifier({
     pkg: {
       name,
-      version,
+      version: DOCUSAURUS_VERSION,
     },
     // Check is in background so it's fine to use a small value like 1h
     // Use 0 for debugging
     updateCheckInterval: 1000 * 60 * 60,
-    // updateCheckInterval: 0
   });
 
   // Hacky way to ensure we check for updates on first run
@@ -72,8 +77,7 @@ export default async function beforeCli() {
    * @param {import('update-notifier').UpdateInfo} update
    */
   function ignoreUpdate(update) {
-    const isCanaryRelease =
-      update && update.current && update.current.startsWith('0.0.0');
+    const isCanaryRelease = update?.current?.startsWith('0.0.0');
     return isCanaryRelease;
   }
 
@@ -98,9 +102,7 @@ export default async function beforeCli() {
       .filter((p) => p.startsWith('@docusaurus'))
       .map((p) => p.concat('@latest'))
       .join(' ');
-    const isYarnUsed = await fs.pathExists(
-      path.resolve(process.cwd(), 'yarn.lock'),
-    );
+    const isYarnUsed = await fs.pathExists(path.resolve('yarn.lock'));
     const upgradeCommand = isYarnUsed
       ? `yarn upgrade ${siteDocusaurusPackagesForUpdate}`
       : `npm i ${siteDocusaurusPackagesForUpdate}`;
@@ -127,7 +129,7 @@ export default async function beforeCli() {
     console.log(docusaurusUpdateMessage);
   }
 
-  // notify user if node version needs to be updated
+  // Notify user if node version needs to be updated
   if (!semver.satisfies(process.version, requiredVersion)) {
     logger.error('Minimum Node.js version not met :(');
     logger.info`You are using Node.js number=${process.version}, Requirement: Node.js number=${requiredVersion}.`;

package/bin/docusaurus.mjs

@@ -11,7 +11,7 @@
 import logger from '@docusaurus/logger';
 import fs from 'fs-extra';
 import cli from 'commander';
-import {createRequire} from 'module';
+import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
 import {
   build,
   swizzle,
@@ -29,9 +29,7 @@ await beforeCli();
 
 const resolveDir = (dir = '.') => fs.realpath(dir);
 
-cli
-  .version(createRequire(import.meta.url)('../package.json').version)
-  .usage('<command> [options]');
+cli.version(DOCUSAURUS_VERSION).usage('<command> [options]');
 
 cli
   .command('build [siteDir]')
@@ -56,14 +54,8 @@ cli
     '--no-minify',
     'build website without minimizing JS bundles (default: false)',
   )
-  .action(async (siteDir, {bundleAnalyzer, config, outDir, locale, minify}) => {
-    build(await resolveDir(siteDir), {
-      bundleAnalyzer,
-      outDir,
-      config,
-      locale,
-      minify,
-    });
+  .action(async (siteDir, options) => {
+    build(await resolveDir(siteDir), options);
   });
 
 cli
@@ -88,9 +80,9 @@ cli
     'copy TypeScript theme files when possible (default: false)',
   )
   .option('--danger', 'enable swizzle for unsafe component of themes')
-  .action(async (themeName, componentName, siteDir, options) => {
-    swizzle(await resolveDir(siteDir), themeName, componentName, options);
-  });
+  .action(async (themeName, componentName, siteDir, options) =>
+    swizzle(await resolveDir(siteDir), themeName, componentName, options),
+  );
 
 cli
   .command('deploy [siteDir]')
@@ -111,13 +103,9 @@ cli
     '--skip-build',
     'skip building website before deploy it (default: false)',
   )
-  .action(async (siteDir, {outDir, skipBuild, config}) => {
-    deploy(await resolveDir(siteDir), {
-      outDir,
-      config,
-      skipBuild,
-    });
-  });
+  .action(async (siteDir, options) =>
+    deploy(await resolveDir(siteDir), options),
+  );
 
 cli
   .command('start [siteDir]')
@@ -138,18 +126,8 @@ cli
     '--poll [interval]',
     'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds',
   )
-  .action(
-    async (siteDir, {port, host, locale, config, hotOnly, open, poll}) => {
-      start(await resolveDir(siteDir), {
-        port,
-        host,
-        locale,
-        config,
-        hotOnly,
-        open,
-        poll,
-      });
-    },
+  .action(async (siteDir, options) =>
+    start(await resolveDir(siteDir), options),
   );
 
 cli
@@ -166,44 +144,25 @@ cli
   .option('-p, --port <port>', 'use specified port (default: 3000)')
   .option('--build', 'build website before serving (default: false)')
   .option('-h, --host <host>', 'use specified host (default: localhost)')
-  .action(
-    async (
-      siteDir,
-      {
-        dir = 'build',
-        port = 3000,
-        host = 'localhost',
-        build: buildSite = false,
-        config,
-      },
-    ) => {
-      serve(await resolveDir(siteDir), {
-        dir,
-        port,
-        build: buildSite,
-        config,
-        host,
-      });
-    },
+  .action(async (siteDir, options) =>
+    serve(await resolveDir(siteDir), options),
   );
 
 cli
   .command('clear [siteDir]')
   .description('Remove build artifacts.')
-  .action(async (siteDir) => {
-    clear(await resolveDir(siteDir));
-  });
+  .action(async (siteDir) => clear(await resolveDir(siteDir)));
 
 cli
   .command('write-translations [siteDir]')
   .description('Extract required translations of your site.')
   .option(
     '-l, --locale <locale>',
-    'the locale folder to write the translations\n"--locale fr" will write translations in ./i18n/fr folder)',
+    'the locale folder to write the translations.\n"--locale fr" will write translations in the ./i18n/fr folder.',
   )
   .option(
     '--override',
-    'by default, we only append missing translation messages to existing translation files. This option allows to override existing translation messages. Make sure to commit or backup your existing translations, as they may be overridden',
+    'By default, we only append missing translation messages to existing translation files. This option allows to override existing translation messages. Make sure to commit or backup your existing translations, as they may be overridden. (default: false)',
   )
   .option(
     '--config <config>',
@@ -211,20 +170,10 @@ cli
   )
   .option(
     '--messagePrefix <messagePrefix>',
-    'allows to init new written messages with a given prefix. This might help you to highlight untranslated message to make them stand out in the UI',
+    'Allows to init new written messages with a given prefix. This might help you to highlight untranslated message by making them stand out in the UI (default: "")',
   )
-  .action(
-    async (
-      siteDir,
-      {locale = undefined, override = false, messagePrefix = '', config},
-    ) => {
-      writeTranslations(await resolveDir(siteDir), {
-        locale,
-        override,
-        config,
-        messagePrefix,
-      });
-    },
+  .action(async (siteDir, options) =>
+    writeTranslations(await resolveDir(siteDir), options),
   );
 
 cli
@@ -245,36 +194,35 @@ cli.arguments('<command>').action((cmd) => {
 });
 
 /**
- * @param {string} command
+ * @param {string | undefined} command
  */
 function isInternalCommand(command) {
-  return [
-    'start',
-    'build',
-    'swizzle',
-    'deploy',
-    'serve',
-    'clear',
-    'write-translations',
-    'write-heading-ids',
-  ].includes(command);
+  return (
+    command &&
+    [
+      'start',
+      'build',
+      'swizzle',
+      'deploy',
+      'serve',
+      'clear',
+      'write-translations',
+      'write-heading-ids',
+    ].includes(command)
+  );
 }
 
-async function run() {
-  if (!isInternalCommand(process.argv.slice(2)[0])) {
-    await externalCommand(cli, await resolveDir('.'));
-  }
-
-  cli.parse(process.argv);
+if (!isInternalCommand(process.argv.slice(2)[0])) {
+  await externalCommand(cli, await resolveDir('.'));
+}
 
-  if (!process.argv.slice(2).length) {
-    cli.outputHelp();
-  }
+if (!process.argv.slice(2).length) {
+  cli.outputHelp();
 }
 
-run();
+cli.parse(process.argv);
 
 process.on('unhandledRejection', (err) => {
-  logger.error(err);
+  logger.error(err instanceof Error ? err.stack : err);
   process.exit(1);
 });

package/lib/babel/preset.js

@@ -7,7 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const path_1 = tslib_1.__importDefault(require("path"));
 function getTransformOptions(isServer) {
     const absoluteRuntimePath = path_1.default.dirname(require.resolve(`@babel/runtime/package.json`));
     return {
@@ -68,7 +68,7 @@ function getTransformOptions(isServer) {
     };
 }
 function babelPresets(api) {
-    const callerName = api.caller((caller) => caller === null || caller === void 0 ? void 0 : caller.name);
+    const callerName = api.caller((caller) => caller?.name);
     return getTransformOptions(callerName === 'server');
 }
 exports.default = babelPresets;

package/lib/client/.eslintrc.js

@@ -11,12 +11,11 @@ module.exports = {
       'error',
       {
         patterns: [
-          // prevent importing lodash in client bundle
-          // prefer shipping vanilla JS
+          // Prevent importing lodash in client bundle for bundle size
           'lodash',
           'lodash.**',
           'lodash/**',
-          // prevent importing server code in client bundle
+          // Prevent importing server code in client bundle
           '**/../babel/**',
           '**/../server/**',
           '**/../commands/**',

package/lib/client/App.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import './client-lifecycles-dispatcher';
+import '@generated/client-modules';
 export default function App(): JSX.Element;

package/lib/client/App.js

@@ -5,25 +5,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
+import '@generated/client-modules';
 import routes from '@generated/routes';
-import renderRoutes from './exports/renderRoutes';
-import { BrowserContextProvider } from './exports/browserContext';
-import { DocusaurusContextProvider } from './exports/docusaurusContext';
+import { useLocation } from '@docusaurus/router';
+import normalizeLocation from './normalizeLocation';
+import renderRoutes from '@docusaurus/renderRoutes';
+import { BrowserContextProvider } from './browserContext';
+import { DocusaurusContextProvider } from './docusaurusContext';
 import PendingNavigation from './PendingNavigation';
-import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
+import BaseUrlIssueBanner from './BaseUrlIssueBanner';
+import SiteMetadataDefaults from './SiteMetadataDefaults';
 import Root from '@theme/Root';
-import './client-lifecycles-dispatcher';
+import SiteMetadata from '@theme/SiteMetadata';
 // TODO, quick fix for CSS insertion order
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
 import Error from '@theme/Error';
 export default function App() {
+    const routeElement = renderRoutes(routes);
+    const location = useLocation();
     return (<ErrorBoundary fallback={Error}>
       <DocusaurusContextProvider>
         <BrowserContextProvider>
           <Root>
+            <SiteMetadataDefaults />
+            <SiteMetadata />
             <BaseUrlIssueBanner />
-            <PendingNavigation routes={routes} delay={1000}>
-              {renderRoutes(routes)}
+            <PendingNavigation location={normalizeLocation(location)}>
+              {routeElement}
             </PendingNavigation>
           </Root>
         </BrowserContextProvider>

package/lib/client/{baseUrlIssueBanner/BaseUrlIssueBanner.d.ts → BaseUrlIssueBanner/index.d.ts}

@@ -6,17 +6,22 @@
  */
 /// <reference types="react" />
 import './styles.module.css';
+declare const InsertBannerWindowAttribute = "__DOCUSAURUS_INSERT_BASEURL_BANNER";
 declare global {
     interface Window {
-        __DOCUSAURUS_INSERT_BASEURL_BANNER: boolean;
+        [InsertBannerWindowAttribute]: boolean;
     }
 }
 /**
  * We want to help the users with a bad baseUrl configuration (very common
- * error) Help message is inlined, and hidden if JS or CSS is able to load
+ * error). Help message is inlined, and hidden if JS or CSS is able to load.
+ *
+ * This component only inserts the base URL banner for the homepage, to avoid
+ * polluting every statically rendered page.
+ *
  * Note: it might create false positives (ie network failures): not a big deal
- * Note: we only inline this for the homepage to avoid polluting all the site's
- * pages
+ *
  * @see https://github.com/facebook/docusaurus/pull/3621
  */
-export default function BaseUrlIssueBanner(): JSX.Element | null;
+export default function MaybeBaseUrlIssueBanner(): JSX.Element | null;
+export {};

package/lib/client/{baseUrlIssueBanner/BaseUrlIssueBanner.js → BaseUrlIssueBanner/index.js}

@@ -30,7 +30,7 @@ function createInlineHtmlBanner(baseUrl) {
 </div>
 `;
 }
-// fn needs to work for older browsers!
+// Needs to work for older browsers!
 function createInlineScript(baseUrl) {
     return `
 window['${InsertBannerWindowAttribute}'] = true;
@@ -60,7 +60,7 @@ function insertBanner() {
 }
 `;
 }
-function BaseUrlIssueBannerEnabled() {
+function BaseUrlIssueBanner() {
     const { siteConfig: { baseUrl }, } = useDocusaurusContext();
     // useLayoutEffect fires before DOMContentLoaded.
     // It gives the opportunity to avoid inserting the banner in the first place
@@ -68,7 +68,10 @@ function BaseUrlIssueBannerEnabled() {
         window[InsertBannerWindowAttribute] = false;
     }, []);
     return (<>
-      {!ExecutionEnvironment.canUseDOM && (<Head>
+      {!ExecutionEnvironment.canUseDOM && (
+        // Safe to use `ExecutionEnvironment`, because `Head` is purely
+        // side-effect and doesn't affect hydration
+        <Head>
           <script>{createInlineScript(baseUrl)}</script>
         </Head>)}
       <div id={BannerContainerId}/>
@@ -76,17 +79,19 @@ function BaseUrlIssueBannerEnabled() {
 }
 /**
  * We want to help the users with a bad baseUrl configuration (very common
- * error) Help message is inlined, and hidden if JS or CSS is able to load
+ * error). Help message is inlined, and hidden if JS or CSS is able to load.
+ *
+ * This component only inserts the base URL banner for the homepage, to avoid
+ * polluting every statically rendered page.
+ *
  * Note: it might create false positives (ie network failures): not a big deal
- * Note: we only inline this for the homepage to avoid polluting all the site's
- * pages
+ *
  * @see https://github.com/facebook/docusaurus/pull/3621
  */
-export default function BaseUrlIssueBanner() {
+export default function MaybeBaseUrlIssueBanner() {
     const { siteConfig: { baseUrl, baseUrlIssueBanner }, } = useDocusaurusContext();
     const { pathname } = useLocation();
-    // returns true for the homepage during SRR
     const isHomePage = pathname === baseUrl;
     const enabled = baseUrlIssueBanner && isHomePage;
-    return enabled ? <BaseUrlIssueBannerEnabled /> : null;
+    return enabled ? <BaseUrlIssueBanner /> : null;
 }

package/lib/client/ClientLifecyclesDispatcher.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 ReactElement } from 'react';
+import type { ClientModule } from '@docusaurus/types';
+import type { Location } from 'history';
+export declare function dispatchLifecycleAction<K extends keyof ClientModule>(lifecycleAction: K, ...args: Parameters<NonNullable<ClientModule[K]>>): () => void;
+declare function ClientLifecyclesDispatcher({ children, location, previousLocation, }: {
+    children: ReactElement;
+    location: Location;
+    previousLocation: Location | null;
+}): JSX.Element;
+export default ClientLifecyclesDispatcher;

package/lib/client/ClientLifecyclesDispatcher.js

@@ -0,0 +1,34 @@
+/**
+ * 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 { useLayoutEffect } from 'react';
+import clientModules from '@generated/client-modules';
+export function dispatchLifecycleAction(lifecycleAction, ...args) {
+    const callbacks = clientModules.map((clientModule) => {
+        const lifecycleFunction = (clientModule?.default?.[lifecycleAction] ??
+            clientModule[lifecycleAction]);
+        return lifecycleFunction?.(...args);
+    });
+    return () => callbacks.forEach((cb) => cb?.());
+}
+function ClientLifecyclesDispatcher({ children, location, previousLocation, }) {
+    useLayoutEffect(() => {
+        if (previousLocation !== location) {
+            const { hash } = location;
+            if (!hash) {
+                window.scrollTo(0, 0);
+            }
+            else {
+                const id = decodeURIComponent(hash.substring(1));
+                const element = document.getElementById(id);
+                element?.scrollIntoView();
+            }
+            dispatchLifecycleAction('onRouteDidUpdate', { previousLocation, location });
+        }
+    }, [previousLocation, location]);
+    return children;
+}
+export default ClientLifecyclesDispatcher;

package/lib/client/LinksCollector.d.ts

@@ -13,7 +13,7 @@ declare type StatefulLinksCollector = LinksCollector & {
 };
 export declare const createStatefulLinksCollector: () => StatefulLinksCollector;
 export declare const useLinksCollector: () => LinksCollector;
-export declare function ProvideLinksCollector({ children, linksCollector, }: {
+export declare function LinksCollectorProvider({ children, linksCollector, }: {
     children: ReactNode;
     linksCollector: LinksCollector;
 }): JSX.Element;

package/lib/client/LinksCollector.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { useContext, createContext } from 'react';
+import React, { useContext } from 'react';
 export const createStatefulLinksCollector = () => {
     // Set to dedup, as it's not useful to collect multiple times the same link
     const allLinks = new Set();
@@ -15,13 +15,12 @@ export const createStatefulLinksCollector = () => {
         getCollectedLinks: () => [...allLinks],
     };
 };
-const Context = createContext({
+const Context = React.createContext({
     collectLink: () => {
-        // noop by default for client
-        // we only use the broken links checker server-side
+        // No-op for client. We only use the broken links checker server-side.
     },
 });
 export const useLinksCollector = () => useContext(Context);
-export function ProvideLinksCollector({ children, linksCollector, }) {
+export function LinksCollectorProvider({ children, linksCollector, }) {
     return <Context.Provider value={linksCollector}>{children}</Context.Provider>;
 }

package/lib/client/PendingNavigation.d.ts

@@ -4,29 +4,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="node" />
 import React from 'react';
-import { type RouteComponentProps } from 'react-router-dom';
-import type { RouteConfig } from 'react-router-config';
 import type { Location } from 'history';
-import './nprogress.css';
-interface Props extends RouteComponentProps {
-    readonly routes: RouteConfig[];
-    readonly delay: number;
+declare type Props = {
     readonly location: Location;
-}
-interface State {
+    readonly children: JSX.Element;
+};
+declare type State = {
     nextRouteHasLoaded: boolean;
-}
+};
 declare class PendingNavigation extends React.Component<Props, State> {
-    previousLocation: Location | null;
-    progressBarTimeout: NodeJS.Timeout | null;
+    private previousLocation;
+    private routeUpdateCleanupCb;
     constructor(props: Props);
     shouldComponentUpdate(nextProps: Props, nextState: State): boolean;
-    private clearProgressBarTimeout;
-    private startProgressBar;
-    private stopProgressBar;
     render(): JSX.Element;
 }
-declare const _default: React.ComponentClass<Pick<Props, "routes" | "delay">, any> & import("react-router").WithRouterStatics<typeof PendingNavigation>;
-export default _default;
+export default PendingNavigation;