refactor(v2): cleanup console output (#4979)

* refactor(v2): cleanup console output

* fix jest issue

Co-authored-by: slorber <lorber.sebastien@gmail.com>

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap

@@ -1,11 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`sidebar site with wrong sidebar content 1`] = `
-"Bad sidebar file at 'packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/wrong-sidebars.json'.
+"Invalid sidebar file at \\"packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/wrong-sidebars.json\\".
 These sidebar document ids do not exist:
-- goku,
+- goku
 
-Available document ids=
+Available document ids are:
 - foo/bar
 - foo/baz
 - headingAsTitle

packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts

@@ -35,7 +35,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] No version tag specified!. Pass the version you wish to create as an argument. Ex: 1.0.0"`,
+      `"[docs]: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0."`,
     );
     expect(() =>
       cliDocsVersionCommand(
@@ -45,7 +45,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] No version tag specified!. Pass the version you wish to create as an argument. Ex: 1.0.0"`,
+      `"[docs]: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0."`,
     );
     expect(() =>
       cliDocsVersionCommand(
@@ -55,7 +55,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] No version tag specified!. Pass the version you wish to create as an argument. Ex: 1.0.0"`,
+      `"[docs]: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0."`,
     );
   });
 
@@ -68,7 +68,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Do not include slash (/) or (\\\\). Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Do not include slash (/) or backslash (\\\\). Try something like: 1.0.0."`,
     );
     expect(() =>
       cliDocsVersionCommand(
@@ -78,7 +78,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Do not include slash (/) or (\\\\). Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Do not include slash (/) or backslash (\\\\). Try something like: 1.0.0."`,
     );
   });
 
@@ -91,7 +91,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Length must <= 32 characters. Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0."`,
     );
   });
 
@@ -104,7 +104,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Do not name your version \\".\\" or \\"..\\". Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Do not name your version \\".\\" or \\"..\\". Try something like: 1.0.0."`,
     );
     expect(() =>
       cliDocsVersionCommand(
@@ -114,7 +114,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Do not name your version \\".\\" or \\"..\\". Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Do not name your version \\".\\" or \\"..\\". Try something like: 1.0.0."`,
     );
   });
 
@@ -127,7 +127,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0."`,
     );
     expect(() =>
       cliDocsVersionCommand(
@@ -137,7 +137,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0."`,
     );
     expect(() =>
       cliDocsVersionCommand(
@@ -147,7 +147,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] Invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0"`,
+      `"[docs]: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0."`,
     );
   });
 
@@ -160,7 +160,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] This version already exists!. Use a version tag that does not already exist."`,
+      `"[docs]: this version already exists! Use a version tag that does not already exist."`,
     );
   });
 
@@ -174,7 +174,7 @@ describe('docsVersion', () => {
         DEFAULT_OPTIONS,
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"[docs] There is no docs to version !"`,
+      `"[docs]: there is no docs to version!"`,
     );
   });
 
@@ -218,7 +218,7 @@ describe('docsVersion', () => {
       getVersionsFilePath(simpleSiteDir, DEFAULT_PLUGIN_ID),
     );
     expect(versions).toEqual(['1.0.0']);
-    expect(consoleMock).toHaveBeenCalledWith('[docs] Version 1.0.0 created!');
+    expect(consoleMock).toHaveBeenCalledWith('[docs]: version 1.0.0 created!');
 
     copyMock.mockRestore();
     writeMock.mockRestore();
@@ -271,7 +271,7 @@ describe('docsVersion', () => {
       getVersionsFilePath(versionedSiteDir, DEFAULT_PLUGIN_ID),
     );
     expect(versions).toEqual(['2.0.0', '1.0.1', '1.0.0', 'withSlugs']);
-    expect(consoleMock).toHaveBeenCalledWith('[docs] Version 2.0.0 created!');
+    expect(consoleMock).toHaveBeenCalledWith('[docs]: version 2.0.0 created!');
 
     copyMock.mockRestore();
     writeMock.mockRestore();
@@ -322,7 +322,7 @@ describe('docsVersion', () => {
     );
     expect(versions).toEqual(['2.0.0', '1.0.0']);
     expect(consoleMock).toHaveBeenCalledWith(
-      '[community] Version 2.0.0 created!',
+      '[community]: version 2.0.0 created!',
     );
 
     copyMock.mockRestore();

packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts

@@ -453,7 +453,7 @@ describe('simple site', () => {
         }),
       );
     }).toThrowErrorMatchingInlineSnapshot(
-      `"Document id [Hello/world] cannot include \\"/\\"."`,
+      `"Document id \\"Hello/world\\" cannot include slash."`,
     );
   });
 

packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts

@@ -44,8 +44,10 @@ function getDocById(version: LoadedVersion, unversionedId: string) {
   const doc = findDocById(version, unversionedId);
   if (!doc) {
     throw new Error(
-      `No doc found with id=${unversionedId} in version ${version.versionName}.
-Available ids=\n- ${version.docs.map((d) => d.unversionedId).join('\n- ')}`,
+      `No doc found with id "${unversionedId}" in version ${
+        version.versionName
+      }.
+Available ids are:\n- ${version.docs.map((d) => d.unversionedId).join('\n- ')}`,
     );
   }
   return doc;
@@ -85,7 +87,7 @@ const createFakeActions = (contentDir: string) => {
       key.startsWith(prefix),
     );
     if (!entry) {
-      throw new Error(`No created entry found for prefix=[${prefix}]
+      throw new Error(`No created entry found for prefix "${prefix}".
 Entries created:
 - ${Object.keys(dataContainer).join('\n- ')}
         `);
@@ -151,8 +153,8 @@ describe('sidebar', () => {
       );
       await plugin.loadContent!();
     }).rejects.toThrowErrorMatchingInlineSnapshot(`
-            "The path to the sidebar file does not exist at [wrong-path-sidebar.json].
-            Please set the docs [sidebarPath] field in your config file to:
+            "The path to the sidebar file does not exist at \\"wrong-path-sidebar.json\\".
+            Please set the docs \\"sidebarPath\\" field in your config file to:
             - a sidebars path that exists
             - false: to disable the sidebar
             - undefined: for Docusaurus generates it automatically"
@@ -217,7 +219,7 @@ describe('empty/no docs website', () => {
     await expect(
       plugin.loadContent!(),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"Docs version current has no docs! At least one doc should exist at path=[docs]"`,
+      `"Docs version \\"current\\" has no docs! At least one doc should exist at \\"docs\\"."`,
     );
   });
 
@@ -231,11 +233,11 @@ describe('empty/no docs website', () => {
         }),
       ),
     ).toThrowError(
-      `The docs folder does not exist for version [current]. A docs folder is expected to be found at ${
+      `The docs folder does not exist for version "current". A docs folder is expected to be found at ${
         process.platform === 'win32'
           ? 'path\\doesnt\\exist'
           : 'path/doesnt/exist'
-      }`,
+      }.`,
     );
   });
 });

packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts

@@ -60,7 +60,7 @@ describe('loadSidebars', () => {
       'sidebars-category-wrong-items.json',
     );
     expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}. \\"items\\" must be an array."`,
+      `"Error loading {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}: \\"items\\" must be an array."`,
     );
   });
 
@@ -70,7 +70,7 @@ describe('loadSidebars', () => {
       'sidebars-category-wrong-label.json',
     );
     expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading {\\"type\\":\\"category\\",\\"label\\":true,\\"items\\":[\\"doc1\\"]}. \\"label\\" must be a string."`,
+      `"Error loading {\\"type\\":\\"category\\",\\"label\\":true,\\"items\\":[\\"doc1\\"]}: \\"label\\" must be a string."`,
     );
   });
 
@@ -80,7 +80,7 @@ describe('loadSidebars', () => {
       'sidebars-doc-id-not-string.json',
     );
     expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading {\\"type\\":\\"doc\\",\\"id\\":[\\"doc1\\"]}. \\"id\\" must be a string."`,
+      `"Error loading {\\"type\\":\\"doc\\",\\"id\\":[\\"doc1\\"]}: \\"id\\" must be a string."`,
     );
   });
 
@@ -102,22 +102,23 @@ describe('loadSidebars', () => {
   test('sidebars link wrong label', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-label.json');
     expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading {\\"type\\":\\"link\\",\\"label\\":false,\\"href\\":\\"https://github.com\\"}. \\"label\\" must be a string."`,
+      `"Error loading {\\"type\\":\\"link\\",\\"label\\":false,\\"href\\":\\"https://github.com\\"}: \\"label\\" must be a string."`,
     );
   });
 
   test('sidebars link wrong href', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-href.json');
     expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading {\\"type\\":\\"link\\",\\"label\\":\\"GitHub\\",\\"href\\":[\\"example.com\\"]}. \\"href\\" must be a string."`,
+      `"Error loading {\\"type\\":\\"link\\",\\"label\\":\\"GitHub\\",\\"href\\":[\\"example.com\\"]}: \\"href\\" must be a string."`,
     );
   });
 
   test('sidebars with unknown sidebar item type', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-unknown-type.json');
-    expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(
-      `"Unknown sidebar item type [superman]. Sidebar item={\\"type\\":\\"superman\\"} "`,
-    );
+    expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot(`
+      "Unknown sidebar item type \\"superman\\". Sidebar item is {\\"type\\":\\"superman\\"}.
+      "
+    `);
   });
 
   test('sidebars with known sidebar item type but wrong field', async () => {

packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts

@@ -174,7 +174,7 @@ describe('simple site', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Bad docs options.versions: unknown versions found: unknownVersionName1,unknownVersionName2. Available version names are: current"`,
+      `"Invalid docs option \\"versions\\": unknown versions (unknownVersionName1,unknownVersionName2) found. Available version names are: current"`,
     );
   });
 
@@ -187,7 +187,7 @@ describe('simple site', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Docs: using disableVersioning=true option on a non-versioned site does not make sense"`,
+      `"Docs: using \\"disableVersioning=true\\" option on a non-versioned site does not make sense."`,
     );
   });
 
@@ -200,7 +200,7 @@ describe('simple site', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: includeCurrentVersion=false disableVersioning=false"`,
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=false\\"."`,
     );
   });
 });
@@ -527,7 +527,7 @@ describe('versioned site, pluginId=default', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: includeCurrentVersion=false disableVersioning=true"`,
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`,
     );
   });
 
@@ -543,7 +543,7 @@ describe('versioned site, pluginId=default', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Bad docs options.onlyIncludeVersions: an empty array is not allowed, at least one version is needed"`,
+      `"Invalid docs option \\"onlyIncludeVersions\\": an empty array is not allowed, at least one version is needed."`,
     );
   });
 
@@ -559,7 +559,7 @@ describe('versioned site, pluginId=default', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Bad docs options.onlyIncludeVersions: unknown versions found: unknownVersion1,unknownVersion2. Available version names are: current, 1.0.1, 1.0.0, withSlugs"`,
+      `"Invalid docs option \\"onlyIncludeVersions\\": unknown versions (unknownVersion1,unknownVersion2) found. Available version names are: current, 1.0.1, 1.0.0, withSlugs"`,
     );
   });
 
@@ -576,7 +576,7 @@ describe('versioned site, pluginId=default', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Bad docs options.lastVersion: if you use both the onlyIncludeVersions and lastVersion options, then lastVersion must be present in the provided onlyIncludeVersions array"`,
+      `"Invalid docs option \\"lastVersion\\": if you use both the \\"onlyIncludeVersions\\" and \\"lastVersion\\" options, then \\"lastVersion\\" must be present in the provided \\"onlyIncludeVersions\\" array."`,
     );
   });
 
@@ -595,7 +595,7 @@ describe('versioned site, pluginId=default', () => {
         context: defaultContext,
       });
     }).toThrowErrorMatchingInlineSnapshot(
-      `"The versions file should contain an array of versions! Found content={\\"invalid\\":\\"json\\"}"`,
+      `"The versions file should contain an array of versions! Found content: {\\"invalid\\":\\"json\\"}"`,
     );
     mock.mockRestore();
   });
@@ -712,7 +712,7 @@ describe('versioned site, pluginId=community', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: includeCurrentVersion=false disableVersioning=true"`,
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`,
     );
   });
 });

packages/docusaurus-plugin-content-docs/src/cli.ts

@@ -92,23 +92,23 @@ export function cliDocsVersionCommand(
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
   const pluginIdLogPrefix =
-    pluginId === DEFAULT_PLUGIN_ID ? '[docs] ' : `[${pluginId}] `;
+    pluginId === DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
 
   if (!version) {
     throw new Error(
-      `${pluginIdLogPrefix}No version tag specified!. Pass the version you wish to create as an argument. Ex: 1.0.0`,
+      `${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`,
     );
   }
 
   if (version.includes('/') || version.includes('\\')) {
     throw new Error(
-      `${pluginIdLogPrefix}Invalid version tag specified! Do not include slash (/) or (\\). Try something like: 1.0.0`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Do not include slash (/) or backslash (\\). Try something like: 1.0.0.`,
     );
   }
 
   if (version.length > 32) {
     throw new Error(
-      `${pluginIdLogPrefix}Invalid version tag specified! Length must <= 32 characters. Try something like: 1.0.0`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`,
     );
   }
 
@@ -117,13 +117,13 @@ export function cliDocsVersionCommand(
   // eslint-disable-next-line no-control-regex
   if (/[<>:"|?*\x00-\x1F]/g.test(version)) {
     throw new Error(
-      `${pluginIdLogPrefix}Invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`,
     );
   }
 
   if (/^\.\.?$/.test(version)) {
     throw new Error(
-      `${pluginIdLogPrefix}Invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`,
     );
   }
 
@@ -137,7 +137,7 @@ export function cliDocsVersionCommand(
   // Check if version already exists.
   if (versions.includes(version)) {
     throw new Error(
-      `${pluginIdLogPrefix}This version already exists!. Use a version tag that does not already exist.`,
+      `${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`,
     );
   }
 
@@ -151,7 +151,7 @@ export function cliDocsVersionCommand(
     const newVersionDir = path.join(versionedDir, `version-${version}`);
     fs.copySync(docsDir, newVersionDir);
   } else {
-    throw new Error(`${pluginIdLogPrefix}There is no docs to version !`);
+    throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
   }
 
   createVersionedSidebarFile({
@@ -166,5 +166,5 @@ export function cliDocsVersionCommand(
   fs.ensureDirSync(path.dirname(versionsJSONFile));
   fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
 
-  console.log(`${pluginIdLogPrefix}Version ${version} created!`);
+  console.log(`${pluginIdLogPrefix}: version ${version} created!`);
 }

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts

@@ -35,12 +35,12 @@ describe('docsClientUtils', () => {
     expect(() =>
       getActivePlugin(data, '/', {failfast: true}),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Can't find active docs plugin for pathname=/, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: /ios, /android"`,
+      `"Can't find active docs plugin for \\"/\\" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: /ios, /android"`,
     );
     expect(() =>
       getActivePlugin(data, '/xyz', {failfast: true}),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Can't find active docs plugin for pathname=/xyz, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: /ios, /android"`,
+      `"Can't find active docs plugin for \\"/xyz\\" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: /ios, /android"`,
     );
 
     const activePluginIos: ActivePlugin = {

packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts

@@ -57,7 +57,7 @@ export function getActivePlugin(
 
   if (!activePlugin && options.failfast) {
     throw new Error(
-      `Can't find active docs plugin for pathname=${pathname}, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(
+      `Can't find active docs plugin for "${pathname}" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(
         allPluginDatas,
       )
         .map((plugin) => plugin.path)

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

@@ -149,7 +149,7 @@ export function processDocMetadata({
 
   const baseID: string = frontMatter.id ?? unprefixedFileName;
   if (baseID.includes('/')) {
-    throw new Error(`Document id [${baseID}] cannot include "/".`);
+    throw new Error(`Document id "${baseID}" cannot include slash.`);
   }
 
   // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -144,12 +144,12 @@ export default function pluginContentDocs(
         const docFiles = await readVersionDocs(versionMetadata, options);
         if (docFiles.length === 0) {
           throw new Error(
-            `Docs version ${
+            `Docs version "${
               versionMetadata.versionName
-            } has no docs! At least one doc should exist at path=[${path.relative(
+            }" has no docs! At least one doc should exist at "${path.relative(
               siteDir,
               versionMetadata.contentPath,
-            )}]`,
+            )}".`,
           );
         }
         async function processVersionDoc(docFile: DocFile) {

packages/docusaurus-plugin-content-docs/src/markdown/linkify.ts

@@ -17,7 +17,7 @@ function getVersion(filePath: string, options: DocsMarkdownOption) {
   );
   if (!versionFound) {
     throw new Error(
-      `Unexpected, markdown file does not belong to any docs version! file=${filePath}`,
+      `Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`,
     );
   }
   return versionFound;

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -130,9 +130,9 @@ export function validateOptions({
   if (typeof options.excludeNextVersionDocs !== 'undefined') {
     console.log(
       chalk.red(
-        `The docs plugin option excludeNextVersionDocs=${
+        `The docs plugin option "excludeNextVersionDocs=${
           options.excludeNextVersionDocs
-        } is deprecated. Use the includeCurrentVersion=${!options.excludeNextVersionDocs} option instead!"`,
+        }" is deprecated. Use the "includeCurrentVersion=${!options.excludeNextVersionDocs}" option instead!"`,
       ),
     );
     options.includeCurrentVersion = !options.excludeNextVersionDocs;

packages/docusaurus-plugin-content-docs/src/props.ts

@@ -27,8 +27,8 @@ export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
 
     if (!docMetadata) {
       throw new Error(
-        `Bad sidebars file. The document id '${docId}' was used in the sidebar, but no document with this id could be found.
-Available document ids=
+        `Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
+Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`,
       );
     }

packages/docusaurus-plugin-content-docs/src/sidebarItemsGenerator.ts

@@ -74,7 +74,7 @@ async function readCategoryMetadatasFile(
       } catch (e) {
         console.error(
           chalk.red(
-            `The docs sidebar category metadata file looks invalid!\nPath=${filePath}`,
+            `The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`,
           ),
         );
         throw e;
@@ -139,7 +139,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async functio
   ): string {
     if (!isInAutogeneratedDir(doc)) {
       throw new Error(
-        'getDocDirRelativeToAutogenDir() can only be called for  subdocs of the sidebar autogen dir',
+        'getDocDirRelativeToAutogenDir() can only be called for subdocs of the sidebar autogen dir.',
       );
     }
     // Is there a node API to compare 2 relative paths more easily?
@@ -160,7 +160,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async functio
   if (docs.length === 0) {
     console.warn(
       chalk.yellow(
-        `No docs found in dir ${item.dirName}: can't auto-generate a sidebar`,
+        `No docs found in dir ${item.dirName}: can't auto-generate a sidebar.`,
       ),
     );
   }

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

@@ -118,18 +118,18 @@ function assertIsCategory(
   assertItem(item, ['items', 'label', 'collapsed', 'customProps']);
   if (typeof item.label !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+      `Error loading ${JSON.stringify(item)}: "label" must be a string.`,
     );
   }
   if (!Array.isArray(item.items)) {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "items" must be an array.`,
+      `Error loading ${JSON.stringify(item)}: "items" must be an array.`,
     );
   }
   // "collapsed" is an optional property
   if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "collapsed" must be a boolean.`,
+      `Error loading ${JSON.stringify(item)}: "collapsed" must be a boolean.`,
     );
   }
 }
@@ -140,14 +140,14 @@ function assertIsAutogenerated(
   assertItem(item, ['dirName', 'customProps']);
   if (typeof item.dirName !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "dirName" must be a string.`,
+      `Error loading ${JSON.stringify(item)}: "dirName" must be a string.`,
     );
   }
   if (item.dirName.startsWith('/') || item.dirName.endsWith('/')) {
     throw new Error(
       `Error loading ${JSON.stringify(
         item,
-      )}. "dirName" must be a dir path relative to the docs folder root, and should not start or end with /`,
+      )}: "dirName" must be a dir path relative to the docs folder root, and should not start or end with slash`,
     );
   }
 }
@@ -158,13 +158,13 @@ function assertIsDoc(
   assertItem(item, ['id', 'label', 'customProps']);
   if (typeof item.id !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "id" must be a string.`,
+      `Error loading ${JSON.stringify(item)}: "id" must be a string.`,
     );
   }
 
   if (item.label && typeof item.label !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+      `Error loading ${JSON.stringify(item)}: "label" must be a string.`,
     );
   }
 }
@@ -175,12 +175,12 @@ function assertIsLink(
   assertItem(item, ['href', 'label', 'customProps']);
   if (typeof item.href !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "href" must be a string.`,
+      `Error loading ${JSON.stringify(item)}: "href" must be a string.`,
     );
   }
   if (typeof item.label !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+      `Error loading ${JSON.stringify(item)}: "label" must be a string.`,
     );
   }
 }
@@ -224,12 +224,12 @@ function normalizeItem(item: SidebarItemJSON): UnprocessedSidebarItem[] {
     default: {
       const extraMigrationError =
         item.type === 'subcategory'
-          ? "Docusaurus v2: 'subcategory' has been renamed as 'category'"
+          ? 'Docusaurus v2: "subcategory" has been renamed as "category".'
           : '';
       throw new Error(
-        `Unknown sidebar item type [${
+        `Unknown sidebar item type "${
           item.type
-        }]. Sidebar item=${JSON.stringify(item)} ${extraMigrationError}`,
+        }". Sidebar item is ${JSON.stringify(item)}.\n${extraMigrationError}`,
       );
     }
   }
@@ -485,11 +485,13 @@ export function createSidebarsUtils(sidebars: Sidebars) {
     const invalidSidebarDocIds = difference(allSidebarDocIds, validDocIds);
     if (invalidSidebarDocIds.length > 0) {
       throw new Error(
-        `Bad sidebar file at '${toMessageRelativeFilePath(sidebarFilePath)}'.
+        `Invalid sidebar file at "${toMessageRelativeFilePath(
+          sidebarFilePath,
+        )}".
 These sidebar document ids do not exist:
-- ${invalidSidebarDocIds.sort().join('\n- ')},
+- ${invalidSidebarDocIds.sort().join('\n- ')}
 
-Available document ids=
+Available document ids are:
 - ${validDocIds.sort().join('\n- ')}`,
       );
     }

packages/docusaurus-plugin-content-docs/src/slug.ts

@@ -47,8 +47,8 @@ export default function getSlug({
 
   if (!isValidPathname(slug)) {
     throw new Error(
-      `We couldn't compute a valid slug for document with id=${baseID} in folder=${dirName}
-The slug we computed looks invalid: ${slug}
+      `We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
+The slug we computed looks invalid: ${slug}.
 Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
 By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
 

packages/docusaurus-plugin-content-docs/src/versions.ts

@@ -59,12 +59,12 @@ export function getVersionsFilePath(siteDir: string, pluginId: string): string {
 function ensureValidVersionString(version: unknown): asserts version is string {
   if (typeof version !== 'string') {
     throw new Error(
-      `versions should be strings. Found type=[${typeof version}] for version=[${version}]`,
+      `Versions should be strings. Found type "${typeof version}" for version "${version}".`,
     );
   }
   // Should we forbid versions with special chars like / ?
   if (version.trim().length === 0) {
-    throw new Error(`Invalid version=[${version}]`);
+    throw new Error(`Invalid version "${version}".`);
   }
 }
 
@@ -73,7 +73,7 @@ function ensureValidVersionArray(
 ): asserts versionArray is string[] {
   if (!(versionArray instanceof Array)) {
     throw new Error(
-      `The versions file should contain an array of versions! Found content=${JSON.stringify(
+      `The versions file should contain an array of versions! Found content: ${JSON.stringify(
         versionArray,
       )}`,
     );
@@ -106,7 +106,7 @@ function readVersionNames(
 
   if (!versionFileContent && options.disableVersioning) {
     throw new Error(
-      `Docs: using disableVersioning=${options.disableVersioning} option on a non-versioned site does not make sense`,
+      `Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`,
     );
   }
 
@@ -124,7 +124,7 @@ function readVersionNames(
 
   if (versions.length === 0) {
     throw new Error(
-      `It is not possible to use docs without any version. Please check the configuration of these options: includeCurrentVersion=${options.includeCurrentVersion} disableVersioning=${options.disableVersioning}`,
+      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`,
     );
   }
 
@@ -342,10 +342,10 @@ function checkVersionMetadataPaths({
 
   if (!fs.existsSync(contentPath)) {
     throw new Error(
-      `The docs folder does not exist for version [${versionName}]. A docs folder is expected to be found at ${path.relative(
+      `The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path.relative(
         siteDir,
         contentPath,
-      )}`,
+      )}.`,
     );
   }
 
@@ -358,11 +358,11 @@ function checkVersionMetadataPaths({
     typeof sidebarFilePath === 'string' &&
     !fs.existsSync(sidebarFilePath)
   ) {
-    throw new Error(`The path to the sidebar file does not exist at [${path.relative(
+    throw new Error(`The path to the sidebar file does not exist at "${path.relative(
       siteDir,
       sidebarFilePath,
-    )}].
-Please set the docs [sidebarPath] field in your config file to:
+    )}".
+Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
 - false: to disable the sidebar
 - undefined: for Docusaurus generates it automatically`);
@@ -403,16 +403,16 @@ function checkVersionsOptions(
   );
   if (unknownVersionConfigNames.length > 0) {
     throw new Error(
-      `Bad docs options.versions: unknown versions found: ${unknownVersionConfigNames.join(
+      `Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(
         ',',
-      )}. ${availableVersionNamesMsg}`,
+      )}) found. ${availableVersionNamesMsg}`,
     );
   }
 
   if (options.onlyIncludeVersions) {
     if (options.onlyIncludeVersions.length === 0) {
       throw new Error(
-        `Bad docs options.onlyIncludeVersions: an empty array is not allowed, at least one version is needed`,
+        `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
       );
     }
     const unknownOnlyIncludeVersionNames = difference(
@@ -421,9 +421,9 @@ function checkVersionsOptions(
     );
     if (unknownOnlyIncludeVersionNames.length > 0) {
       throw new Error(
-        `Bad docs options.onlyIncludeVersions: unknown versions found: ${unknownOnlyIncludeVersionNames.join(
+        `Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(
           ',',
-        )}. ${availableVersionNamesMsg}`,
+        )}) found. ${availableVersionNamesMsg}`,
       );
     }
     if (
@@ -431,7 +431,7 @@ function checkVersionsOptions(
       !options.onlyIncludeVersions.includes(options.lastVersion)
     ) {
       throw new Error(
-        `Bad docs options.lastVersion: if you use both the onlyIncludeVersions and lastVersion options, then lastVersion must be present in the provided onlyIncludeVersions array`,
+        `Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`,
       );
     }
   }