@docusaurus/core 2.0.0-beta.2 → 2.0.0-beta.20

package/bin/beforeCli.mjs

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+
+// @ts-check
+
+import logger from '@docusaurus/logger';
+import fs from 'fs-extra';
+import semver from 'semver';
+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');
+/** @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,
+  engines: {node: requiredVersion},
+} = packageJson;
+
+/**
+ * Notify user if `@docusaurus` packages are outdated
+ *
+ * Note: this is a 2-step process to avoid delaying cli usage by awaiting a
+ * response:
+ * - 1st run: trigger background job to check releases + store result
+ * - 2nd run: display potential update to users
+ *
+ * cache data is stored in `~/.config/configstore/update-notifier-@docusaurus`
+ */
+export default async function beforeCli() {
+  const notifier = updateNotifier({
+    pkg: {
+      name,
+      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,
+  });
+
+  // Hacky way to ensure we check for updates on first run
+  // Note: the notification will only happen in the 2nd run
+  // See https://github.com/yeoman/update-notifier/issues/209
+  try {
+    if (
+      notifier.config &&
+      // @ts-expect-error: this is an internal API
+      !notifier.disabled &&
+      Date.now() - notifier.config.get('lastUpdateCheck') < 50
+    ) {
+      notifier.config.set('lastUpdateCheck', 0);
+      notifier.check();
+    }
+  } catch (err) {
+    // Do not stop cli if this fails, see https://github.com/facebook/docusaurus/issues/5400
+    logger.error(err);
+  }
+
+  /**
+   * We don't want to display update message for canary releases.
+   * See https://github.com/facebook/docusaurus/issues/5378
+   * @param {import('update-notifier').UpdateInfo} update
+   */
+  function ignoreUpdate(update) {
+    const isCanaryRelease = update?.current?.startsWith('0.0.0');
+    return isCanaryRelease;
+  }
+
+  if (
+    notifier.config &&
+    notifier.update &&
+    semver.lt(notifier.update.current, notifier.update.latest)
+  ) {
+    // Because notifier clears cached data after reading it, leading to notifier
+    // not consistently displaying the update.
+    // See https://github.com/yeoman/update-notifier/issues/209
+    notifier.config.set('update', notifier.update);
+
+    if (ignoreUpdate(notifier.update)) {
+      return;
+    }
+
+    const siteDocusaurusPackagesForUpdate = Object.keys({
+      ...sitePkg.dependencies,
+      ...sitePkg.devDependencies,
+    })
+      .filter((p) => p.startsWith('@docusaurus'))
+      .map((p) => p.concat('@latest'))
+      .join(' ');
+    const isYarnUsed = await fs.pathExists(path.resolve('yarn.lock'));
+    const upgradeCommand = isYarnUsed
+      ? `yarn upgrade ${siteDocusaurusPackagesForUpdate}`
+      : `npm i ${siteDocusaurusPackagesForUpdate}`;
+
+    /** @type {import('boxen').Options} */
+    const boxenOptions = {
+      padding: 1,
+      margin: 1,
+      align: 'center',
+      borderColor: 'yellow',
+      borderStyle: 'round',
+    };
+
+    const docusaurusUpdateMessage = boxen(
+      `Update available ${logger.dim(
+        `${notifier.update.current}`,
+      )} → ${logger.green(`${notifier.update.latest}`)}
+
+  To upgrade Docusaurus packages with the latest version, run the following command:
+  ${logger.code(upgradeCommand)}`,
+      boxenOptions,
+    );
+
+    console.log(docusaurusUpdateMessage);
+  }
+
+  // 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}.`;
+    process.exit(1);
+  }
+}

package/bin/docusaurus.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ */
+
+// @ts-check
+
+import logger from '@docusaurus/logger';
+import fs from 'fs-extra';
+import cli from 'commander';
+import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
+import {
+  build,
+  swizzle,
+  deploy,
+  start,
+  externalCommand,
+  serve,
+  clear,
+  writeTranslations,
+  writeHeadingIds,
+} from '../lib/index.js';
+import beforeCli from './beforeCli.mjs';
+
+await beforeCli();
+
+const resolveDir = (dir = '.') => fs.realpath(dir);
+
+cli.version(DOCUSAURUS_VERSION).usage('<command> [options]');
+
+cli
+  .command('build [siteDir]')
+  .description('Build website.')
+  .option(
+    '--bundle-analyzer',
+    'visualize size of webpack output files with an interactive zoomable tree map (default: false)',
+  )
+  .option(
+    '--out-dir <dir>',
+    'the full path for the new output directory, relative to the current workspace (default: build)',
+  )
+  .option(
+    '--config <config>',
+    'path to docusaurus config file (default: `[siteDir]/docusaurus.config.js`)',
+  )
+  .option(
+    '-l, --locale <locale>',
+    'build the site in a specified locale. Build all known locales otherwise',
+  )
+  .option(
+    '--no-minify',
+    'build website without minimizing JS bundles (default: false)',
+  )
+  .action(async (siteDir, options) => {
+    build(await resolveDir(siteDir), options);
+  });
+
+cli
+  .command('swizzle [themeName] [componentName] [siteDir]')
+  .description(
+    'Wraps or ejects the original theme files into website folder for customization.',
+  )
+  .option(
+    '-w, --wrap',
+    'Creates a wrapper around the original theme component.\nAllows rendering other components before/after the original theme component.',
+  )
+  .option(
+    '-e, --eject',
+    'Ejects the full source code of the original theme component.\nAllows overriding the original component entirely with your own UI and logic.',
+  )
+  .option(
+    '-l, --list',
+    'only list the available themes/components without further prompting (default: false)',
+  )
+  .option(
+    '-t, --typescript',
+    '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),
+  );
+
+cli
+  .command('deploy [siteDir]')
+  .description('Deploy website to GitHub pages.')
+  .option(
+    '-l, --locale <locale>',
+    'deploy the site in a specified locale. Deploy all known locales otherwise',
+  )
+  .option(
+    '--out-dir <dir>',
+    'the full path for the new output directory, relative to the current workspace (default: build)',
+  )
+  .option(
+    '--config <config>',
+    'path to Docusaurus config file (default: `[siteDir]/docusaurus.config.js`)',
+  )
+  .option(
+    '--skip-build',
+    'skip building website before deploy it (default: false)',
+  )
+  .action(async (siteDir, options) =>
+    deploy(await resolveDir(siteDir), options),
+  );
+
+cli
+  .command('start [siteDir]')
+  .description('Start the development server.')
+  .option('-p, --port <port>', 'use specified port (default: 3000)')
+  .option('-h, --host <host>', 'use specified host (default: localhost)')
+  .option('-l, --locale <locale>', 'use specified site locale')
+  .option(
+    '--hot-only',
+    'do not fallback to page refresh if hot reload fails (default: false)',
+  )
+  .option(
+    '--config <config>',
+    'path to Docusaurus config file (default: `[siteDir]/docusaurus.config.js`)',
+  )
+  .option('--no-open', 'do not open page in the browser (default: false)')
+  .option(
+    '--poll [interval]',
+    'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds',
+  )
+  .action(async (siteDir, options) =>
+    start(await resolveDir(siteDir), options),
+  );
+
+cli
+  .command('serve [siteDir]')
+  .description('Serve website locally.')
+  .option(
+    '--dir <dir>',
+    'the full path for the new output directory, relative to the current workspace (default: build)',
+  )
+  .option(
+    '--config <config>',
+    'path to Docusaurus config file (default: `[siteDir]/docusaurus.config.js`)',
+  )
+  .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, options) =>
+    serve(await resolveDir(siteDir), options),
+  );
+
+cli
+  .command('clear [siteDir]')
+  .description('Remove build artifacts.')
+  .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 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. (default: false)',
+  )
+  .option(
+    '--config <config>',
+    'path to Docusaurus config file (default:`[siteDir]/docusaurus.config.js`)',
+  )
+  .option(
+    '--messagePrefix <messagePrefix>',
+    '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, options) =>
+    writeTranslations(await resolveDir(siteDir), options),
+  );
+
+cli
+  .command('write-heading-ids [siteDir] [files...]')
+  .description('Generate heading ids in Markdown content.')
+  .option(
+    '--maintain-case',
+    "keep the headings' casing, otherwise make all lowercase (default: false)",
+  )
+  .option('--overwrite', 'overwrite existing heading IDs (default: false)')
+  .action(async (siteDir, files, options) =>
+    writeHeadingIds(await resolveDir(siteDir), files, options),
+  );
+
+cli.arguments('<command>').action((cmd) => {
+  cli.outputHelp();
+  logger.error`    Unknown command name=${cmd}.`;
+});
+
+/**
+ * @param {string | undefined} command
+ */
+function isInternalCommand(command) {
+  return (
+    command &&
+    [
+      'start',
+      'build',
+      'swizzle',
+      'deploy',
+      'serve',
+      'clear',
+      'write-translations',
+      'write-heading-ids',
+    ].includes(command)
+  );
+}
+
+if (!isInternalCommand(process.argv.slice(2)[0])) {
+  await externalCommand(cli, await resolveDir('.'));
+}
+
+if (!process.argv.slice(2).length) {
+  cli.outputHelp();
+}
+
+cli.parse(process.argv);
+
+process.on('unhandledRejection', (err) => {
+  logger.error(err instanceof Error ? err.stack : err);
+  process.exit(1);
+});

package/lib/babel/preset.d.ts

@@ -1,3 +1,8 @@
-import { ConfigAPI, TransformOptions } from '@babel/core';
-declare function babelPresets(api: ConfigAPI): TransformOptions;
-export default babelPresets;
+/**
+ * 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 { ConfigAPI, TransformOptions } from '@babel/core';
+export default function babelPresets(api: ConfigAPI): TransformOptions;

package/lib/babel/preset.js

@@ -1,17 +1,18 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
 /**
  * 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.
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 function getTransformOptions(isServer) {
     const absoluteRuntimePath = path_1.default.dirname(require.resolve(`@babel/runtime/package.json`));
     return {
-        // All optional newlines and whitespace will be omitted when generating code in compact mode
+        // All optional newlines and whitespace will be omitted when generating code
+        // in compact mode
         compact: true,
         presets: [
             isServer
@@ -46,9 +47,9 @@ function getTransformOptions(isServer) {
                 {
                     corejs: false,
                     helpers: true,
-                    // By default, it assumes @babel/runtime@7.0.0. Since we use >7.0.0, better to
-                    // explicitly specify the version so that it can reuse the helper better
-                    // See https://github.com/babel/babel/issues/10261
+                    // By default, it assumes @babel/runtime@7.0.0. Since we use >7.0.0,
+                    // better to explicitly specify the version so that it can reuse the
+                    // helper better. See https://github.com/babel/babel/issues/10261
                     // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
                     version: require('@babel/runtime/package.json').version,
                     regenerator: true,
@@ -67,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,17 +11,15 @@ 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/**',
           '**/../webpack/**',
-          '**/../constants',
         ],
       },
     ],

package/lib/client/App.d.ts

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

package/lib/client/App.js

@@ -4,34 +4,37 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { useEffect, useState } from 'react';
+import React from 'react';
+import '@generated/client-modules';
 import routes from '@generated/routes';
-import siteConfig from '@generated/docusaurus.config';
-import globalData from '@generated/globalData';
-import i18n from '@generated/i18n';
-import codeTranslations from '@generated/codeTranslations';
-import siteMetadata from '@generated/site-metadata';
-import renderRoutes from './exports/renderRoutes';
-import DocusaurusContext from './exports/context';
+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';
-function App() {
-    const [isClient, setIsClient] = useState(false);
-    useEffect(() => {
-        setIsClient(true);
-    }, []);
-    return (React.createElement(DocusaurusContext.Provider, { value: {
-            siteConfig,
-            siteMetadata,
-            globalData,
-            i18n,
-            codeTranslations,
-            isClient,
-        } },
-        React.createElement(Root, null,
-            React.createElement(BaseUrlIssueBanner, null),
-            React.createElement(PendingNavigation, { routes: routes }, renderRoutes(routes)))));
+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 location={normalizeLocation(location)}>
+              {routeElement}
+            </PendingNavigation>
+          </Root>
+        </BrowserContextProvider>
+      </DocusaurusContextProvider>
+    </ErrorBoundary>);
 }
-export default App;

package/lib/client/BaseUrlIssueBanner/index.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.
+ */
+/// <reference types="react" />
+import './styles.module.css';
+declare const InsertBannerWindowAttribute = "__DOCUSAURUS_INSERT_BASEURL_BANNER";
+declare global {
+    interface Window {
+        [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.
+ *
+ * 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
+ *
+ * @see https://github.com/facebook/docusaurus/pull/3621
+ */
+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,28 +60,38 @@ 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
     useLayoutEffect(() => {
         window[InsertBannerWindowAttribute] = false;
     }, []);
-    return (React.createElement(React.Fragment, null,
-        !ExecutionEnvironment.canUseDOM && (React.createElement(Head, null,
-            React.createElement("script", null, createInlineScript(baseUrl)))),
-        React.createElement("div", { id: BannerContainerId })));
+    return (<>
+      {!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}/>
+    </>);
 }
-// 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
-// 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() {
+/**
+ * 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.
+ *
+ * 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
+ *
+ * @see https://github.com/facebook/docusaurus/pull/3621
+ */
+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 ? React.createElement(BaseUrlIssueBannerEnabled, null) : 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,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.
+ */
+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 scrollAfterNavigation(location) {
+    const { hash } = location;
+    if (!hash) {
+        window.scrollTo(0, 0);
+    }
+    else {
+        const id = decodeURIComponent(hash.substring(1));
+        const element = document.getElementById(id);
+        element?.scrollIntoView();
+    }
+}
+function ClientLifecyclesDispatcher({ children, location, previousLocation, }) {
+    useLayoutEffect(() => {
+        if (previousLocation !== location) {
+            if (previousLocation) {
+                scrollAfterNavigation(location);
+            }
+            dispatchLifecycleAction('onRouteDidUpdate', { previousLocation, location });
+        }
+    }, [previousLocation, location]);
+    return children;
+}
+export default ClientLifecyclesDispatcher;