feat(logger): new "url" format, add double quotes around paths (#7019)

* refactor(logger): add double quotes around paths

* Introduce url formatter

* Fix

packages/create-docusaurus/src/index.ts

@@ -271,7 +271,7 @@ export default async function init(
         return logger.red('Invalid repository URL');
       },
       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'})`,
+(e.g: url=${'https://github.com/ownerName/repoName.git'})`,
     });
     ({gitStrategy} = await prompts({
       type: 'select',
@@ -318,7 +318,7 @@ export default async function init(
   logger.info('Creating new Docusaurus project...');
 
   if (isValidGitRepoUrl(template)) {
-    logger.info`Cloning Git template path=${template}...`;
+    logger.info`Cloning Git template url=${template}...`;
     if (!gitStrategies.includes(gitStrategy)) {
       logger.error`Invalid git strategy: name=${gitStrategy}. Value must be one of ${gitStrategies.join(
         ', ',
@@ -416,7 +416,7 @@ export default async function init(
   }
 
   const useNpm = pkgManager === 'npm';
-  logger.success`Created path=${cdpath}.`;
+  logger.success`Created name=${cdpath}.`;
   logger.info`Inside that directory, you can run several commands:
 
   code=${`${pkgManager} start`}

packages/docusaurus-logger/README.md

@@ -8,7 +8,8 @@ It exports a single object as default export: `logger`. `logger` has the followi
 
 - 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.
+  - `path`: formats a file path.
+  - `url`: formats a URL.
   - `id`: formats an identifier.
   - `code`: formats a code snippet.
   - `subdue`: subdues the text.
@@ -34,6 +35,7 @@ To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to
 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`
+- `url=`: `url`
 - `name=`: `id`
 - `code=`: `code`
 - `subdue=`: `subdue`

packages/docusaurus-logger/src/__tests__/index.test.ts

@@ -11,7 +11,12 @@ import logger from '../index';
 describe('formatters', () => {
   it('path', () => {
     // cSpell:ignore mhey
-    expect(logger.path('hey')).toMatchInlineSnapshot(`"hey"`);
+    expect(logger.path('hey')).toMatchInlineSnapshot(`"\\"hey\\""`);
+  });
+  it('url', () => {
+    expect(logger.url('https://docusaurus.io/')).toMatchInlineSnapshot(
+      `"https://docusaurus.io/"`,
+    );
   });
   it('id', () => {
     expect(logger.name('hey')).toMatchInlineSnapshot(`"hey"`);
@@ -40,8 +45,7 @@ describe('interpolate', () => {
     expect(
       logger.interpolate`The package at path=${'packages/docusaurus'} has number=${10} files. name=${'Babel'} is exported here subdue=${'(as a preset)'} that you can with code=${"require.resolve('@docusaurus/core/lib/babel/preset')"}`,
     ).toMatchInlineSnapshot(
-      // cSpell:ignore mpackages
+      `"The package at \\"packages/docusaurus\\" has 10 files. Babel is exported here (as a preset) that you can with \`require.resolve('@docusaurus/core/lib/babel/preset')\`"`,
-      `"The package at packages/docusaurus has 10 files. Babel is exported here (as a preset) that you can with \`require.resolve('@docusaurus/core/lib/babel/preset')\`"`,
     );
   });
   it('interpolates arrays with flags', () => {

packages/docusaurus-logger/src/index.ts

@@ -9,7 +9,8 @@ import chalk, {type Chalk} from 'chalk';
 
 type InterpolatableValue = string | number | (string | number)[];
 
-const path = (msg: unknown): string => chalk.cyan(chalk.underline(msg));
+const path = (msg: unknown): string => chalk.cyan(chalk.underline(`"${msg}"`));
+const url = (msg: unknown): string => chalk.cyan(chalk.underline(msg));
 const name = (msg: unknown): string => chalk.blue(chalk.bold(msg));
 const code = (msg: unknown): string => chalk.cyan(`\`${msg}\``);
 const subdue: Chalk = chalk.gray;
@@ -30,6 +31,8 @@ function interpolate(
       switch (flag[0]) {
         case 'path=':
           return path;
+        case 'url=':
+          return url;
         case 'number=':
           return num;
         case 'name=':
@@ -131,6 +134,7 @@ const logger = {
   bold: chalk.bold,
   dim: chalk.dim,
   path,
+  url,
   name,
   code,
   subdue,

packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts

@@ -65,7 +65,7 @@ function normalizeSidebar(
     throw new Error(
       logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
         sidebar,
-      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
+      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
     );
   }
 

packages/docusaurus/src/client/serverEntry.tsx

@@ -55,7 +55,7 @@ export default async function render(
 
     if (isNotDefinedErrorRegex.test((err as Error).message)) {
       logger.info`It looks like you are using code that should run on the client-side only.
-To get around it, try using code=${'<BrowserOnly>'} (path=${'https://docusaurus.io/docs/docusaurus-core/#browseronly'}) or code=${'ExecutionEnvironment'} (path=${'https://docusaurus.io/docs/docusaurus-core/#executionenvironment'}).
+To get around it, try using code=${'<BrowserOnly>'} (url=${'https://docusaurus.io/docs/docusaurus-core/#browseronly'}) or code=${'ExecutionEnvironment'} (url=${'https://docusaurus.io/docs/docusaurus-core/#executionenvironment'}).
 It might also require to wrap your client code in code=${'useEffect'} hook and/or import a third-party library dynamically (if any).`;
     }
 

packages/docusaurus/src/server/plugins/index.ts

@@ -230,7 +230,7 @@ export async function loadPlugins({
       // TODO remove this deprecated lifecycle soon
       // deprecated since alpha-60
       // TODO, 1 user reported usage of this lifecycle! https://github.com/facebook/docusaurus/issues/3918
-      logger.error`Plugin code=${'routesLoaded'} lifecycle is deprecated. If you think we should keep this lifecycle, please report here: path=${'https://github.com/facebook/docusaurus/issues/3918'}`;
+      logger.error`Plugin code=${'routesLoaded'} lifecycle is deprecated. If you think we should keep this lifecycle, please report here: url=${'https://github.com/facebook/docusaurus/issues/3918'}`;
 
       await plugin.routesLoaded(pluginsRouteConfigs);
     }),