@docusaurus/core 2.0.0-beta.15d451942 → 2.0.0-beta.18

package/bin/beforeCli.mjs

@@ -0,0 +1,133 @@
+/**
+ * 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';
+
+const packageJson = createRequire(import.meta.url)('../package.json');
+const sitePkg = createRequire(path.join(process.cwd(), 'package.json'))(
+  './package.json',
+);
+
+const {
+  name,
+  version,
+  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,
+    },
+    // 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
+  // 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,279 @@
+#!/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 {createRequire} from 'module';
+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(createRequire(import.meta.url)('../package.json').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, {bundleAnalyzer, config, outDir, locale, minify}) => {
+    build(await resolveDir(siteDir), {
+      bundleAnalyzer,
+      outDir,
+      config,
+      locale,
+      minify,
+    });
+  });
+
+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, {outDir, skipBuild, config}) => {
+    deploy(await resolveDir(siteDir), {
+      outDir,
+      config,
+      skipBuild,
+    });
+  });
+
+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, {port, host, locale, config, hotOnly, open, poll}) => {
+      start(await resolveDir(siteDir), {
+        port,
+        host,
+        locale,
+        config,
+        hotOnly,
+        open,
+        poll,
+      });
+    },
+  );
+
+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,
+      {
+        dir = 'build',
+        port = 3000,
+        host = 'localhost',
+        build: buildSite = false,
+        config,
+      },
+    ) => {
+      serve(await resolveDir(siteDir), {
+        dir,
+        port,
+        build: buildSite,
+        config,
+        host,
+      });
+    },
+  );
+
+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 ./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',
+  )
+  .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 to make them stand out in the UI',
+  )
+  .action(
+    async (
+      siteDir,
+      {locale = undefined, override = false, messagePrefix = '', config},
+    ) => {
+      writeTranslations(await resolveDir(siteDir), {
+        locale,
+        override,
+        config,
+        messagePrefix,
+      });
+    },
+  );
+
+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);
+  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/choosePort.js

@@ -14,7 +14,7 @@ const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const detect_port_1 = tslib_1.__importDefault(require("detect-port"));
 const is_root_1 = tslib_1.__importDefault(require("is-root"));
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const prompts_1 = tslib_1.__importDefault(require("prompts"));
 const isInteractive = process.stdout.isTTY;
 const execOptions = {
@@ -22,7 +22,7 @@ const execOptions = {
     stdio: [
         'pipe',
         'pipe',
-        'ignore', // stderr
+        'ignore',
     ],
 };
 // Clears console
@@ -31,21 +31,18 @@ function clearConsole() {
 }
 // Gets process id of what is on port
 function getProcessIdOnPort(port) {
-    return child_process_1.execSync(`lsof -i:${port} -P -t -sTCP:LISTEN`, execOptions)
-        .toString()
+    return (0, child_process_1.execSync)(`lsof -i:${port} -P -t -sTCP:LISTEN`, execOptions)
         .split('\n')[0]
         .trim();
 }
 // Gets process command
 function getProcessCommand(processId) {
-    const command = child_process_1.execSync(`ps -o command -p ${processId} | sed -n 2p`, execOptions);
-    return command.toString().replace(/\n$/, '');
+    const command = (0, child_process_1.execSync)(`ps -o command -p ${processId} | sed -n 2p`, execOptions);
+    return command.replace(/\n$/, '');
 }
 // Gets directory of a process from its process id
 function getDirectoryOfProcessById(processId) {
-    return child_process_1.execSync(`lsof -p ${processId} | awk '$4=="cwd" {for (i=9; i<=NF; i++) printf "%s ", $i}'`, execOptions)
-        .toString()
-        .trim();
+    return (0, child_process_1.execSync)(`lsof -p ${processId} | awk '$4=="cwd" {for (i=9; i<=NF; i++) printf "%s ", $i}'`, execOptions).trim();
 }
 // Gets process on port
 function getProcessForPort(port) {
@@ -53,12 +50,9 @@ function getProcessForPort(port) {
         const processId = getProcessIdOnPort(port);
         const directory = getDirectoryOfProcessById(processId);
         const command = getProcessCommand(processId);
-        return (chalk_1.default.cyan(command) +
-            chalk_1.default.grey(` (pid ${processId})\n`) +
-            chalk_1.default.blue('  in ') +
-            chalk_1.default.cyan(directory));
+        return logger_1.default.interpolate `code=${command} subdue=${`(pid ${processId})`} in path=${directory}`;
     }
-    catch (e) {
+    catch {
         return null;
     }
 }
@@ -67,39 +61,33 @@ function getProcessForPort(port) {
  * to choose another if port is already being used
  */
 async function choosePort(host, defaultPort) {
-    // @ts-expect-error: bad lib typedef?
-    return detect_port_1.default(defaultPort, host).then((port) => new Promise((resolve) => {
+    try {
+        const port = await (0, detect_port_1.default)({ port: defaultPort, hostname: host });
         if (port === defaultPort) {
-            return resolve(port);
+            return port;
         }
-        const message = process.platform !== 'win32' && defaultPort < 1024 && !is_root_1.default()
+        const message = process.platform !== 'win32' && defaultPort < 1024 && !(0, is_root_1.default)()
             ? `Admin permissions are required to run a server on a port below 1024.`
             : `Something is already running on port ${defaultPort}.`;
-        if (isInteractive) {
-            clearConsole();
-            const existingProcess = getProcessForPort(defaultPort);
-            const question = {
-                type: 'confirm',
-                name: 'shouldChangePort',
-                message: `${chalk_1.default.yellow(`${message}${existingProcess ? ` Probably:\n  ${existingProcess}` : ''}`)}\n\nWould you like to run the app on another port instead?`,
-                initial: true,
-            };
-            prompts_1.default(question).then((answer) => {
-                if (answer.shouldChangePort === true) {
-                    resolve(port);
-                }
-                else {
-                    resolve(null);
-                }
-            });
-        }
-        else {
-            console.log(chalk_1.default.red(message));
-            resolve(null);
+        if (!isInteractive) {
+            logger_1.default.error(message);
+            return null;
         }
-        return null;
-    }), (err) => {
-        throw new Error(`${chalk_1.default.red(`Could not find an open port at ${chalk_1.default.bold(host)}.`)}\n${`Network error message: ${err.message}` || err}\n`);
-    });
+        clearConsole();
+        const existingProcess = getProcessForPort(defaultPort);
+        const { shouldChangePort } = await (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'shouldChangePort',
+            message: logger_1.default.yellow(`${logger_1.default.bold('[WARNING]')} ${message}${existingProcess ? ` Probably:\n  ${existingProcess}` : ''}
+
+Would you like to run the app on another port instead?`),
+            initial: true,
+        });
+        return shouldChangePort ? port : null;
+    }
+    catch (err) {
+        logger_1.default.error `Could not find an open port at ${host}.`;
+        throw err;
+    }
 }
 exports.default = choosePort;

package/lib/client/.eslintrc.js

@@ -21,7 +21,6 @@ module.exports = {
           '**/../server/**',
           '**/../commands/**',
           '**/../webpack/**',
-          '**/../constants',
         ],
       },
     ],

package/lib/client/App.d.ts

@@ -6,5 +6,4 @@
  */
 /// <reference types="react" />
 import './client-lifecycles-dispatcher';
-declare function App(): JSX.Element;
-export default App;
+export default function App(): JSX.Element;

package/lib/client/App.js

@@ -4,34 +4,33 @@
  * 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 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 { BrowserContextProvider } from './browserContext';
+import { DocusaurusContextProvider } from './docusaurusContext';
 import PendingNavigation from './PendingNavigation';
 import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
+import SiteMetadataDefaults from './SiteMetadataDefaults';
 import Root from '@theme/Root';
+import SiteMetadata from '@theme/SiteMetadata';
 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)))));
+// TODO, quick fix for CSS insertion order
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import Error from '@theme/Error';
+export default function App() {
+    return (<ErrorBoundary fallback={Error}>
+      <DocusaurusContextProvider>
+        <BrowserContextProvider>
+          <Root>
+            <SiteMetadataDefaults />
+            <SiteMetadata />
+            <BaseUrlIssueBanner />
+            <PendingNavigation routes={routes} delay={1000}>
+              {renderRoutes(routes)}
+            </PendingNavigation>
+          </Root>
+        </BrowserContextProvider>
+      </DocusaurusContextProvider>
+    </ErrorBoundary>);
 }
-export default App;

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 {};