refactor: unify log format with new logger utility

.eslintrc.js

@@ -122,7 +122,7 @@ module.exports = {
     'array-callback-return': WARNING,
     camelcase: WARNING,
     'no-restricted-syntax': WARNING,
-    'no-unused-expressions': WARNING,
+    'no-unused-expressions': [WARNING, {allowTaggedTemplates: true}],
     'global-require': WARNING,
     'prefer-destructuring': WARNING,
     yoda: WARNING,

packages/create-docusaurus/bin/index.js

@@ -6,27 +6,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const chalk = require('chalk');
+// @ts-check
+
+const logger = require('@docusaurus/logger').default;
 const semver = require('semver');
 const path = require('path');
 const program = require('commander');
 const {default: init} = require('../lib');
 const requiredVersion = require('../package.json').engines.node;
 
 if (!semver.satisfies(process.version, requiredVersion)) {
-  console.log(
-    chalk.red(`\nMinimum Node.js version not met :)`) +
-      chalk.yellow(
-        `\nYou are using Node.js ${process.version}, Requirement: Node.js ${requiredVersion}.\n`,
-      ),
-  );
+  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);
 }
 
 function wrapCommand(fn) {
   return (...args) =>
     fn(...args).catch((err) => {
-      console.error(chalk.red(err.stack));
+      logger.error(err.stack);
       process.exitCode = 1;
     });
 }
@@ -58,8 +56,7 @@ program
 
 program.arguments('<command>').action((cmd) => {
   program.outputHelp();
-  console.log(`  ${chalk.red(`\n  Unknown command ${chalk.yellow(cmd)}.`)}`);
-  console.log();
+  logger.error`Unknown command code=${cmd}.`;
 });
 
 program.parse(process.argv);

packages/create-docusaurus/package.json

@@ -23,7 +23,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "chalk": "^4.1.2",
+    "@docusaurus/logger": "2.0.0-beta.13",
     "commander": "^5.1.0",
     "fs-extra": "^10.0.0",
     "lodash": "^4.17.20",

packages/create-docusaurus/src/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import chalk from 'chalk';
+import logger from '@docusaurus/logger';
 import fs from 'fs-extra';
 import {execSync} from 'child_process';
 import prompts, {Choice} from 'prompts';
@@ -131,12 +131,14 @@ export default async function init(
   }
 
   if (!name) {
-    throw new Error(chalk.red('A website name is required.'));
+    logger.error('A website name is required.');
+    process.exit(1);
   }
 
   const dest = path.resolve(rootDir, name);
   if (fs.existsSync(dest)) {
-    throw new Error(`Directory already exists at "${dest}"!`);
+    logger.error`Directory already exists at path=${dest}!`;
+    process.exit(1);
   }
 
   let template = reqTemplate;
@@ -171,10 +173,10 @@ export default async function init(
         if (url && isValidGitRepoUrl(url)) {
           return true;
         }
-        return chalk.red(`Invalid repository URL`);
+        return logger.red('Invalid repository URL');
       },
-      message:
-        'Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.\n(e.g: https://github.com/ownerName/repoName.git)',
+      message: logger.interpolate`Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.
+(e.g: path=${'https://github.com/ownerName/repoName.git'})`,
     });
     template = repoPrompt.gitRepoUrl;
   } else if (template === 'Local template') {
@@ -187,11 +189,11 @@ export default async function init(
           if (fs.existsSync(fullDir)) {
             return true;
           }
-          return chalk.red(
-            `The path ${chalk.magenta(fullDir)} does not exist.`,
+          return logger.red(
+            logger.interpolate`path=${fullDir} does not exist.`,
           );
         }
-        return chalk.red('Please enter a valid path.');
+        return logger.red('Please enter a valid path.');
       },
       message:
         'Enter a local folder path, relative to the current working directory.',
@@ -200,49 +202,47 @@ export default async function init(
   }
 
   if (!template) {
-    throw new Error('Template should not be empty');
+    logger.error('Template should not be empty');
+    process.exit(1);
   }
 
-  console.log(`
-${chalk.cyan('Creating new Docusaurus project...')}
-`);
+  logger.info('Creating new Docusaurus project...');
 
   if (isValidGitRepoUrl(template)) {
-    console.log(`Cloning Git template ${chalk.cyan(template)}...`);
+    logger.info`Cloning Git template path=${template}...`;
     if (
       shell.exec(`git clone --recursive ${template} ${dest}`, {silent: true})
         .code !== 0
     ) {
-      throw new Error(chalk.red(`Cloning Git template ${template} failed!`));
+      logger.error`Cloning Git template name=${template} failed!`;
+      process.exit(1);
     }
   } else if (templates.includes(template)) {
     // Docusaurus templates.
     if (useTS) {
       if (!hasTS(template)) {
-        throw new Error(
-          `Template ${template} doesn't provide the Typescript variant.`,
-        );
+        logger.error`Template name=${template} doesn't provide the Typescript variant.`;
+        process.exit(1);
       }
       template = `${template}${TypeScriptTemplateSuffix}`;
     }
     try {
       await copyTemplate(templatesDir, template, dest);
     } catch (err) {
-      console.log(
-        `Copying Docusaurus template ${chalk.cyan(template)} failed!`,
-      );
+      logger.error`Copying Docusaurus template name=${template} failed!`;
       throw err;
     }
   } else if (fs.existsSync(path.resolve(process.cwd(), template))) {
     const templateDir = path.resolve(process.cwd(), template);
     try {
       await fs.copy(templateDir, dest);
     } catch (err) {
-      console.log(`Copying local template ${templateDir} failed!`);
+      logger.error`Copying local template path=${templateDir} failed!`;
       throw err;
     }
   } else {
-    throw new Error('Invalid template.');
+    logger.error('Invalid template.');
+    process.exit(1);
   }
 
   // Update package.json info.
@@ -253,7 +253,7 @@ ${chalk.cyan('Creating new Docusaurus project...')}
       private: true,
     });
   } catch (err) {
-    console.log(chalk.red('Failed to update package.json.'));
+    logger.error('Failed to update package.json.');
     throw err;
   }
 
@@ -275,7 +275,7 @@ ${chalk.cyan('Creating new Docusaurus project...')}
       ? name
       : path.relative(process.cwd(), name);
   if (!cliOptions.skipInstall) {
-    console.log(`Installing dependencies with ${chalk.cyan(pkgManager)}...`);
+    logger.info`Installing dependencies with name=${pkgManager}...`;
     if (
       shell.exec(
         `cd "${name}" && ${useYarn ? 'yarn' : 'npm install --color always'}`,
@@ -288,36 +288,35 @@ ${chalk.cyan('Creating new Docusaurus project...')}
         },
       ).code !== 0
     ) {
-      console.error(chalk.red('Dependency installation failed.'));
-      console.log(`The site directory has already been created, and you can retry by typing:
+      logger.error('Dependency installation failed.');
+      logger.info`The site directory has already been created, and you can retry by typing:
 
-  ${chalk.cyan('cd')} ${cdpath}
-  ${chalk.cyan(`${pkgManager} install`)}`);
+  code=${`cd ${cdpath}`}
+  code=${`${pkgManager} install`}`;
       process.exit(0);
     }
   }
 
-  console.log(`
-Successfully created "${chalk.cyan(cdpath)}".
-Inside that directory, you can run several commands:
+  logger.success`Created path=${cdpath}.`;
+  logger.info`Inside that directory, you can run several commands:
 
-  ${chalk.cyan(`${pkgManager} start`)}
+  code=${`${pkgManager} start`}
     Starts the development server.
 
-  ${chalk.cyan(`${pkgManager} ${useYarn ? '' : 'run '}build`)}
+  code=${`${pkgManager} ${useYarn ? '' : 'run '}build`}
     Bundles your website into static files for production.
 
-  ${chalk.cyan(`${pkgManager} ${useYarn ? '' : 'run '}serve`)}
+  code=${`${pkgManager} ${useYarn ? '' : 'run '}serve`}
     Serves the built website locally.
 
-  ${chalk.cyan(`${pkgManager} deploy`)}
+  code=${`${pkgManager} deploy`}
     Publishes the website to GitHub pages.
 
 We recommend that you begin by typing:
 
-  ${chalk.cyan('cd')} ${cdpath}
-  ${chalk.cyan(`${pkgManager} start`)}
+  code=${`cd ${cdpath}`}
+  code=${`${pkgManager} start`}
 
 Happy building awesome websites!
-`);
+`;
 }

packages/docusaurus-logger/.npmignore

@@ -0,0 +1,4 @@
+copyUntypedFiles.js
+.tsbuildinfo
+tsconfig*
+__tests__

packages/docusaurus-logger/README.md

@@ -0,0 +1,44 @@
+# `@docusaurus/logger`
+
+An encapsulated logger for semantically formatting console messages.
+
+## APIs
+
+It exports a single object as default export: `logger`. `logger` has the following properties:
+
+- Some useful colors.
+- Formatters. These functions have the same signature as the formatters of `picocolors`. Note that their implementations are not guaranteed. You should only care about their semantics.
+  - `path`: formats a file path or URL.
+  - `id`: formats an identifier.
+  - `code`: formats a code snippet.
+  - `subdue`: subdues the text.
+  - `num`: formats a number.
+- The `interpolate` function. It is a template literal tag.
+- Logging functions. All logging functions can both be used as functions (in which it has the same usage as `console.log`) or template literal tags.
+  - `info`: prints information.
+  - `warn`: prints a warning that should be payed attention to.
+  - `error`: prints an error (not necessarily halting the program) that signals significant problems.
+  - `success`: prints a success message.
+
+### Using the template literal tag
+
+The template literal tag evaluates the template and expressions embedded. `interpolate` returns a new string, while other logging functions prints it. Below is a typical usage:
+
+```js
+logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
+  items.length > 1 ? 'items' : 'item'
+} on the shelf: ${items}
+To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;
+```
+
+An embedded expression is optionally preceded by a flag in the form `%[a-z]+` (a percentage sign followed by a few lowercase letters). If it's not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:
+
+- `path=`: `path`
+- `name=`: `id`
+- `code=`: `code`
+- `subdue=`: `subdue`
+- `number=`: `num`
+
+If the expression is an array, it's formatted by `` `\n- ${array.join('\n- ')}\n` `` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as:
+
+![demo](./demo.png)

packages/docusaurus-logger/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@docusaurus/logger",
+  "version": "2.0.0-beta.13",
+  "description": "An encapsulated logger for semantically formatting console messages.",
+  "main": "./lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-logger"
+  },
+  "bugs": {
+    "url": "https://github.com/facebook/docusaurus/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "tslib": "^2.3.1"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {
+    "@types/supports-color": "^8.1.1"
+  }
+}

packages/docusaurus-logger/src/__mocks__/chalk.js

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+const chalk = require('chalk');
+
+// Force coloring the output even in CI
+module.exports = new chalk.Instance({level: 3});