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\\"} "`,
     );
   });