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/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}`,
+      );
   }
 }