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

package/README.md

@@ -0,0 +1 @@
+# Docusaurus core

package/bin/beforeCli.mjs

@@ -0,0 +1,140 @@
+/**
+ * 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 fs from 'fs-extra';
+import path from 'path';
+import {createRequire} from 'module';
+import logger from '@docusaurus/logger';
+import semver from 'semver';
+import updateNotifier from 'update-notifier';
+import boxen from 'boxen';
+import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
+
+const packageJson = /** @type {import("../package.json")} */ (
+  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,221 @@
+#!/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 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();
+
+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)',
+  )
+  // @ts-expect-error: Promise<string> is not assignable to Promise<void>... but
+  // good enough here.
+  .action(build);
+
+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(swizzle);
+
+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(deploy);
+
+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',
+  )
+  .option(
+    '--no-minify',
+    'build website without minimizing JS bundles (default: false)',
+  )
+  .action(start);
+
+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)')
+  .option(
+    '--no-open',
+    'do not open page in the browser (default: false, or true in CI)',
+  )
+  .action(serve);
+
+cli
+  .command('clear [siteDir]')
+  .description('Remove build artifacts.')
+  .action(clear);
+
+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(writeTranslations);
+
+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(writeHeadingIds);
+
+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);
+}
+
+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,11 +47,12 @@ 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,
+                    version: require('@babel/runtime/package.json')
+                        .version,
                     regenerator: true,
                     useESModules: true,
                     // Undocumented option that lets us encapsulate our runtime, ensuring
@@ -67,7 +69,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/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 PendingNavigation from './PendingNavigation';
-import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
+import { useLocation } from '@docusaurus/router';
+import renderRoutes from '@docusaurus/renderRoutes';
 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';
+import normalizeLocation from './normalizeLocation';
+import { BrowserContextProvider } from './browserContext';
+import { DocusaurusContextProvider } from './docusaurusContext';
+import PendingNavigation from './PendingNavigation';
+import BaseUrlIssueBanner from './BaseUrlIssueBanner';
+import SiteMetadataDefaults from './SiteMetadataDefaults';
+// TODO, quick fix for CSS insertion order
+// eslint-disable-next-line import/order
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+export default function App() {
+    const routeElement = renderRoutes(routes);
+    const location = useLocation();
+    return (<ErrorBoundary>
+      <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,8 +30,9 @@ function createInlineHtmlBanner(baseUrl) {
 </div>
 `;
 }
-// fn needs to work for older browsers!
+// Needs to work for older browsers!
 function createInlineScript(baseUrl) {
+    /* language=js */
     return `
 window['${InsertBannerWindowAttribute}'] = true;
 
@@ -60,28 +61,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;

package/lib/client/LinksCollector.d.ts

@@ -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 { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 declare type LinksCollector = {
     collectLink: (link: string) => void;
 };
@@ -13,8 +13,8 @@ declare type StatefulLinksCollector = LinksCollector & {
 };
 export declare const createStatefulLinksCollector: () => StatefulLinksCollector;
 export declare const useLinksCollector: () => LinksCollector;
-export declare const ProvideLinksCollector: ({ children, linksCollector, }: {
+export declare function LinksCollectorProvider({ children, linksCollector, }: {
     children: ReactNode;
     linksCollector: LinksCollector;
-}) => JSX.Element;
+}): JSX.Element;
 export {};