polish(v2): improve Docusaurus 1 to 2 migration developer experience (#2884)

* improve markdown parsing errors by adding file path to error

* typo commit

* Add default nav item position to right (as v1)

* improve error when sidebar references unexisting document

* parseMarkdownFile: improve errors by providing hint about using "" to avoid parsing errors, if using special characters

* improve subcategory migration error for Unknown sidebar item type

* improve unrecognizedFields error

* typo

* fix inline snapshots

* improve the migration docs

* improve the migration docs

* improve migration doc

* Update migrating-from-v1-to-v2.md

Co-authored-by: Yangshun Tay <tay.yang.shun@gmail.com>

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

@@ -109,6 +109,16 @@ Array [
 ]
 `;
 
+exports[`site with wrong sidebar file 1`] = `
+[Error: Bad sidebars file. The document id 'goku' was used in the sidebar, but no document with this id could be found.
+Available document ids=
+- foo/bar
+- foo/baz
+- hello
+- ipsum
+- lorem]
+`;
+
 exports[`versioned website content 1`] = `
 Array [
   Object {

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

@@ -45,13 +45,7 @@ test('site with wrong sidebar file', async () => {
   const plugin = pluginContentDocs(context, {
     sidebarPath,
   });
-  return plugin
-    .loadContent()
-    .catch((e) =>
-      expect(e).toMatchInlineSnapshot(
-        `[Error: Improper sidebars file, document with id 'goku' not found.]`,
-      ),
-    );
+  return plugin.loadContent().catch((e) => expect(e).toMatchSnapshot());
 });
 
 describe('empty/no docs website', () => {

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

@@ -109,7 +109,7 @@ describe('loadSidebars', () => {
     expect(() =>
       loadSidebars([sidebarPath]),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Unknown sidebar item type: superman"`,
+      `"Unknown sidebar item type [superman]. Sidebar item={\\"type\\":\\"superman\\"} "`,
     );
   });
 

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

@@ -275,16 +275,18 @@ export default function pluginContentDocs(
       });
 
       const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
-        const linkID = item.id;
-        const linkMetadata = docsMetadataRaw[linkID];
+        const docId = item.id;
+        const docMetadata = docsMetadataRaw[docId];
 
-        if (!linkMetadata) {
+        if (!docMetadata) {
           throw new Error(
-            `Improper sidebars file, document with id '${linkID}' not found.`,
+            `Bad sidebars file. The document id '${docId}' was used in the sidebar, but no document with this id could be found.
+Available document ids=
+- ${Object.keys(docsMetadataRaw).sort().join('\n- ')}`,
           );
         }
 
-        const {title, permalink, sidebar_label} = linkMetadata;
+        const {title, permalink, sidebar_label} = docMetadata;
 
         return {
           type: 'link',

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

@@ -5,10 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import fs from 'fs-extra';
 import path from 'path';
 import {
-  parse,
+  parseMarkdownFile,
   aliasedSitePath,
   normalizeUrl,
   getEditUrl,
@@ -65,7 +64,7 @@ export default async function processMetadata({
   const {versioning} = env;
   const filePath = path.join(refDir, source);
 
-  const fileStringPromise = fs.readFile(filePath, 'utf-8');
+  const fileMarkdownPromise = parseMarkdownFile(filePath);
   const lastUpdatedPromise = lastUpdated(filePath, options);
 
   let version;
@@ -92,7 +91,7 @@ export default async function processMetadata({
 
   const docsEditUrl = getEditUrl(relativePath, editUrl);
 
-  const {frontMatter = {}, excerpt} = parse(await fileStringPromise);
+  const {frontMatter = {}, excerpt} = await fileMarkdownPromise;
   const {sidebar_label, custom_edit_url} = frontMatter;
 
   // Default base id is the file name.

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

@@ -136,7 +136,15 @@ function normalizeItem(item: SidebarItemRaw): SidebarItem[] {
       assertIsDoc(item);
       return [item];
     default:
-      throw new Error(`Unknown sidebar item type: ${item.type}`);
+      const extraMigrationError =
+        item.type === 'subcategory'
+          ? "Docusaurus v2: 'subcategory' has been renamed as 'category'"
+          : '';
+      throw new Error(
+        `Unknown sidebar item type [${
+          item.type
+        }]. Sidebar item=${JSON.stringify(item)} ${extraMigrationError}`,
+      );
   }
 }