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>
facebook · Jun 6, 2020 · 1003a15 · 1003a15
1 parent 8aa520c
commit 1003a15
Show file tree

Hide file tree

Showing 11 changed files with 195 additions and 46 deletions.
diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts
@@ -12,7 +12,7 @@ import readingTime from 'reading-time';
 import {Feed} from 'feed';
 import {PluginOptions, BlogPost, DateLink} from './types';
 import {
-  parse,
+  parseMarkdownFile,
   normalizeUrl,
   aliasedSitePath,
   getEditUrl,
@@ -120,8 +120,7 @@ export async function generateBlogPosts(
 
       const editBlogUrl = getEditUrl(relativePath, editUrl);
 
-      const fileString = await fs.readFile(source, 'utf-8');
-      const {frontMatter, content, excerpt} = parse(fileString);
+      const {frontMatter, content, excerpt} = await parseMarkdownFile(source);
 
       if (frontMatter.draft && process.env.NODE_ENV === 'production') {
         return;

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/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 {

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/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', () => {

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts b/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\\"} "`,
     );
   });
 

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/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',

diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/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.

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/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}`,
+      );
   }
 }
 

diff --git a/packages/docusaurus-theme-classic/src/theme/Navbar/index.js b/packages/docusaurus-theme-classic/src/theme/Navbar/index.js
@@ -20,6 +20,9 @@ import useLogo from '@theme/hooks/useLogo';
 
 import styles from './styles.module.css';
 
+// retrocompatible with v1
+const DefaultNavItemPosition = 'right';
+
 function NavLink({
   activeBasePath,
   activeBaseRegex,
@@ -61,7 +64,12 @@ function NavLink({
   );
 }
 
-function NavItem({items, position, className, ...props}) {
+function NavItem({
+  items,
+  position = DefaultNavItemPosition,
+  className,
+  ...props
+}) {
   const navLinkClassNames = (extraClassName, isDropdownItem = false) =>
     classnames(
       {
@@ -147,6 +155,21 @@ function MobileNavItem({items, position, className, ...props}) {
   );
 }
 
+// If split links by left/right
+// if position is unspecified, fallback to right (as v1)
+function splitLinks(links) {
+  const leftLinks = links.filter(
+    (linkItem) => (linkItem.position ?? DefaultNavItemPosition) === 'left',
+  );
+  const rightLinks = links.filter(
+    (linkItem) => (linkItem.position ?? DefaultNavItemPosition) === 'right',
+  );
+  return {
+    leftLinks,
+    rightLinks,
+  };
+}
+
 function Navbar() {
   const {
     siteConfig: {
@@ -178,6 +201,8 @@ function Navbar() {
     [setLightTheme, setDarkTheme],
   );
 
+  const {leftLinks, rightLinks} = splitLinks(links);
+
   return (
     <nav
       ref={navbarRef}
@@ -232,18 +257,14 @@ function Navbar() {
               </strong>
             )}
           </Link>
-          {links
-            .filter((linkItem) => linkItem.position === 'left')
-            .map((linkItem, i) => (
-              <NavItem {...linkItem} key={i} />
-            ))}
+          {leftLinks.map((linkItem, i) => (
+            <NavItem {...linkItem} key={i} />
+          ))}
         </div>
         <div className="navbar__items navbar__items--right">
-          {links
-            .filter((linkItem) => linkItem.position === 'right')
-            .map((linkItem, i) => (
-              <NavItem {...linkItem} key={i} />
-            ))}
+          {rightLinks.map((linkItem, i) => (
+            <NavItem {...linkItem} key={i} />
+          ))}
           {!disableDarkMode && (
             <Toggle
               className={styles.displayOnlyInLargeViewport}

diff --git a/packages/docusaurus-utils/src/index.ts b/packages/docusaurus-utils/src/index.ts
@@ -228,15 +228,14 @@ export function createExcerpt(fileString: string): string | undefined {
   return undefined;
 }
 
-export function parse(
-  fileString: string,
-): {
+type ParsedMarkdown = {
   frontMatter: {
     [key: string]: any;
   };
   content: string;
   excerpt: string | undefined;
-} {
+};
+export function parseMarkdownString(markdownString: string): ParsedMarkdown {
   const options: {} = {
     excerpt: (file: matter.GrayMatterFile<string>): void => {
       // Hacky way of stripping out import statements from the excerpt
@@ -246,8 +245,31 @@ export function parse(
     },
   };
 
-  const {data: frontMatter, content, excerpt} = matter(fileString, options);
-  return {frontMatter, content, excerpt};
+  try {
+    const {data: frontMatter, content, excerpt} = matter(
+      markdownString,
+      options,
+    );
+    return {frontMatter, content, excerpt};
+  } catch (e) {
+    throw new Error(`Error while parsing markdown front matter.
+This can happen if you use special characteres like : in frontmatter values (try using "" around that value)
+${e.message}`);
+  }
+}
+
+export async function parseMarkdownFile(
+  source: string,
+): Promise<ParsedMarkdown> {
+  const markdownString = await fs.readFile(source, 'utf-8');
+  try {
+    return parseMarkdownString(markdownString);
+  } catch (e) {
+    throw new Error(
+      `Error while parsing markdown file ${source}
+${e.message}`,
+    );
+  }
 }
 
 export function normalizeUrl(rawUrls: string[]): string {

diff --git a/packages/docusaurus/src/server/config.ts b/packages/docusaurus/src/server/config.ts
@@ -84,7 +84,9 @@ export function loadConfig(siteDir: string): DocusaurusConfig {
     throw new Error(
       `The field(s) ${formatFields(
         unrecognizedFields,
-      )} are not recognized in ${CONFIG_FILE_NAME}`,
+      )} are not recognized in ${CONFIG_FILE_NAME}.
+If you still want these fields to be in your configuration, put them in the 'customFields' attribute.
+See https://v2.docusaurus.io/docs/docusaurus.config.js/#customfields`,
     );
   }