@docusaurus/core 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/bin/beforeCli.mjs

@@ -0,0 +1,136 @@
+/**
+ * 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 && update.current && 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(process.cwd(), '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.js → docusaurus.mjs}

@@ -1,7 +1,4 @@
 #!/usr/bin/env node
-
-// TODO remove when fixed: https://github.com/Stuk/eslint-plugin-header/issues/39
-/* eslint-disable header/header */
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
@@ -9,14 +6,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const chalk = require('chalk');
-const fs = require('fs-extra');
-const semver = require('semver');
-const path = require('path');
-const cli = require('commander');
-const updateNotifier = require('update-notifier');
-const boxen = require('boxen');
-const {
+// @ts-check
+
+import logger from '@docusaurus/logger';
+import fs from 'fs-extra';
+import cli from 'commander';
+import {createRequire} from 'module';
+import {
   build,
   swizzle,
   deploy,
@@ -26,79 +22,23 @@ const {
   clear,
   writeTranslations,
   writeHeadingIds,
-} = require('../lib');
-const {
-  name,
-  version,
-  engines: {node: requiredVersion},
-} = require('../package.json');
-
-// notify user if @docusaurus packages is outdated
-const notifier = updateNotifier({
-  pkg: {
-    name,
-    version,
-  },
-});
-
-// allow the user to be notified for updates on the first run
-if (notifier.lastUpdateCheck === Date.now()) {
-  notifier.lastUpdateCheck = 0;
-}
-
-if (notifier.update && semver.gt(this.update.latest, this.update.current)) {
-  // eslint-disable-next-line import/no-dynamic-require, global-require
-  const sitePkg = require(path.resolve(process.cwd(), 'package.json'));
-  const siteDocusaurusPackagesForUpdate = Object.keys(sitePkg.dependencies)
-    .filter((p) => p.startsWith('@docusaurus'))
-    .map((p) => p.concat('@latest'))
-    .join(' ');
-  const isYarnUsed = fs.existsSync(path.resolve(process.cwd(), 'yarn.lock'));
-  const upgradeCommand = isYarnUsed
-    ? `yarn upgrade ${siteDocusaurusPackagesForUpdate}`
-    : `npm i ${siteDocusaurusPackagesForUpdate}`;
+} from '../lib/index.js';
+import beforeCli from './beforeCli.mjs';
 
-  const boxenOptions = {
-    padding: 1,
-    margin: 1,
-    align: 'center',
-    borderColor: 'yellow',
-    borderStyle: 'round',
-  };
+await beforeCli();
 
-  const docusaurusUpdateMessage = boxen(
-    `Update available ${chalk.dim(`${notifier.update.current}`)}${chalk.reset(
-      ' → ',
-    )}${chalk.green(
-      `${notifier.update.latest}`,
-    )}\n\nTo upgrade Docusaurus packages with the latest version, run the following command:\n${chalk.cyan(
-      `${upgradeCommand}`,
-    )}`,
-    boxenOptions,
-  );
-
-  console.log(docusaurusUpdateMessage);
-}
-
-// notify user if node version needs to be updated
-if (!semver.satisfies(process.version, requiredVersion)) {
-  console.log(
-    chalk.red(`\nMinimum Node.js version not met :(`) +
-      chalk.yellow(
-        `\n\nYou are using Node.js ${process.version}. We require Node.js ${requiredVersion} or up!\n`,
-      ),
-  );
-  process.exit(1);
-}
+const resolveDir = (dir = '.') => fs.realpath(dir);
 
-cli.version(require('../package.json').version).usage('<command> [options]');
+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 treemap (default: false)',
+    'visualize size of webpack output files with an interactive zoomable tree map (default: false)',
   )
   .option(
     '--out-dir <dir>',
@@ -116,8 +56,8 @@ cli
     '--no-minify',
     'build website without minimizing JS bundles (default: false)',
   )
-  .action((siteDir = '.', {bundleAnalyzer, config, outDir, locale, minify}) => {
-    build(path.resolve(siteDir), {
+  .action(async (siteDir, {bundleAnalyzer, config, outDir, locale, minify}) => {
+    build(await resolveDir(siteDir), {
       bundleAnalyzer,
       outDir,
       config,
@@ -128,20 +68,28 @@ cli
 
 cli
   .command('swizzle [themeName] [componentName] [siteDir]')
-  .description('Copy the theme files into website folder for customization.')
+  .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(
-    '--typescript',
+    '-t, --typescript',
     'copy TypeScript theme files when possible (default: false)',
   )
-  .option('--danger', 'enable swizzle for internal component of themes')
-  .action((themeName, componentName, siteDir = '.', {typescript, danger}) => {
-    swizzle(
-      path.resolve(siteDir),
-      themeName,
-      componentName,
-      typescript,
-      danger,
-    );
+  .option('--danger', 'enable swizzle for unsafe component of themes')
+  .action(async (themeName, componentName, siteDir, options) => {
+    swizzle(await resolveDir(siteDir), themeName, componentName, options);
   });
 
 cli
@@ -163,8 +111,8 @@ cli
     '--skip-build',
     'skip building website before deploy it (default: false)',
   )
-  .action((siteDir = '.', {outDir, skipBuild, config}) => {
-    deploy(path.resolve(siteDir), {
+  .action(async (siteDir, {outDir, skipBuild, config}) => {
+    deploy(await resolveDir(siteDir), {
       outDir,
       config,
       skipBuild,
@@ -191,8 +139,8 @@ cli
     'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds',
   )
   .action(
-    (siteDir = '.', {port, host, locale, config, hotOnly, open, poll}) => {
-      start(path.resolve(siteDir), {
+    async (siteDir, {port, host, locale, config, hotOnly, open, poll}) => {
+      start(await resolveDir(siteDir), {
         port,
         host,
         locale,
@@ -219,8 +167,8 @@ cli
   .option('--build', 'build website before serving (default: false)')
   .option('-h, --host <host>', 'use specified host (default: localhost)')
   .action(
-    (
-      siteDir = '.',
+    async (
+      siteDir,
       {
         dir = 'build',
         port = 3000,
@@ -229,7 +177,7 @@ cli
         config,
       },
     ) => {
-      serve(path.resolve(siteDir), {
+      serve(await resolveDir(siteDir), {
         dir,
         port,
         build: buildSite,
@@ -242,8 +190,8 @@ cli
 cli
   .command('clear [siteDir]')
   .description('Remove build artifacts.')
-  .action((siteDir = '.') => {
-    clear(path.resolve(siteDir));
+  .action(async (siteDir) => {
+    clear(await resolveDir(siteDir));
   });
 
 cli
@@ -266,11 +214,11 @@ cli
     '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(
-    (
-      siteDir = '.',
+    async (
+      siteDir,
       {locale = undefined, override = false, messagePrefix = '', config},
     ) => {
-      writeTranslations(path.resolve(siteDir), {
+      writeTranslations(await resolveDir(siteDir), {
         locale,
         override,
         config,
@@ -280,18 +228,25 @@ cli
   );
 
 cli
-  .command('write-heading-ids [contentDir]')
+  .command('write-heading-ids [siteDir] [files...]')
   .description('Generate heading ids in Markdown content.')
-  .action((siteDir = '.') => {
-    writeHeadingIds(siteDir);
-  });
+  .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();
-  console.log(`  ${chalk.red(`\n  Unknown command ${chalk.yellow(cmd)}.`)}.`);
-  console.log();
+  logger.error`    Unknown command name=${cmd}.`;
 });
 
+/**
+ * @param {string} command
+ */
 function isInternalCommand(command) {
   return [
     'start',
@@ -307,7 +262,7 @@ function isInternalCommand(command) {
 
 async function run() {
   if (!isInternalCommand(process.argv.slice(2)[0])) {
-    await externalCommand(cli, path.resolve('.'));
+    await externalCommand(cli, await resolveDir('.'));
   }
 
   cli.parse(process.argv);
@@ -320,6 +275,6 @@ async function run() {
 run();
 
 process.on('unhandledRejection', (err) => {
-  console.error(chalk.red(err.stack));
+  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 = {
@@ -31,19 +31,19 @@ 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)
+    return (0, child_process_1.execSync)(`lsof -i:${port} -P -t -sTCP:LISTEN`, execOptions)
         .toString()
         .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);
+    const command = (0, child_process_1.execSync)(`ps -o command -p ${processId} | sed -n 2p`, execOptions);
     return command.toString().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)
+    return (0, child_process_1.execSync)(`lsof -p ${processId} | awk '$4=="cwd" {for (i=9; i<=NF; i++) printf "%s ", $i}'`, execOptions)
         .toString()
         .trim();
 }
@@ -53,12 +53,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 +64,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,29 @@
  * 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 './exports/browserContext';
+import { DocusaurusContextProvider } from './exports/docusaurusContext';
 import PendingNavigation from './PendingNavigation';
 import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
 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)))));
+// 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>
+            <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 ProvideLinksCollector({ children, linksCollector, }: {
     children: ReactNode;
     linksCollector: LinksCollector;
-}) => JSX.Element;
+}): JSX.Element;
 export {};