Merge branch 'master' of github.com:facebook/docusaurus into lex111/r…

…eplace-classnames-with-clsx
facebook · Jun 6, 2020 · 4011037 · 4011037
2 parents 93c6fcd + 1003a15
commit 4011037
Show file tree

Hide file tree

Showing 16 changed files with 237 additions and 58 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,8 +64,13 @@ function NavLink({
   );
 }
 
-function NavItem({items, position, className, ...props}) {
-  const navLinkclsx = (extraClassName, isDropdownItem = false) =>
+function NavItem({
+  items,
+  position = DefaultNavItemPosition,
+  className,
+  ...props
+}) {
+  const navLinkClassNames = (extraClassName, isDropdownItem = false) =>
     clsx(
       {
         'navbar__item navbar__link': !isDropdownItem,
@@ -72,7 +80,7 @@ function NavItem({items, position, className, ...props}) {
     );
 
   if (!items) {
-    return <NavLink className={navLinkclsx(className)} {...props} />;
+    return <NavLink className={navLinkClassNames(className)} {...props} />;
   }
 
   return (
@@ -82,7 +90,7 @@ function NavItem({items, position, className, ...props}) {
         'dropdown--right': position === 'right',
       })}>
       <NavLink
-        className={navLinkclsx(className)}
+        className={navLinkClassNames(className)}
         {...props}
         onClick={(e) => e.preventDefault()}
         onKeyDown={(e) => {
@@ -97,7 +105,7 @@ function NavItem({items, position, className, ...props}) {
           <li key={i}>
             <NavLink
               activeClassName="dropdown__link--active"
-              className={navLinkclsx(childItemClassName, true)}
+              className={navLinkClassNames(childItemClassName, true)}
               {...childItemProps}
             />
           </li>
@@ -109,7 +117,7 @@ function NavItem({items, position, className, ...props}) {
 
 function MobileNavItem({items, position, className, ...props}) {
   // Need to destructure position from props so that it doesn't get passed on.
-  const navLinkclsx = (extraClassName, isSubList = false) =>
+  const navLinkClassNames = (extraClassName, isSubList = false) =>
     clsx(
       'menu__link',
       {
@@ -121,22 +129,22 @@ function MobileNavItem({items, position, className, ...props}) {
   if (!items) {
     return (
       <li className="menu__list-item">
-        <NavLink className={navLinkclsx(className)} {...props} />
+        <NavLink className={navLinkClassNames(className)} {...props} />
       </li>
     );
   }
 
   return (
     <li className="menu__list-item">
-      <NavLink className={navLinkclsx(className, true)} {...props}>
+      <NavLink className={navLinkClassNames(className, true)} {...props}>
         {props.label}
       </NavLink>
       <ul className="menu__list">
         {items.map(({className: childItemClassName, ...childItemProps}, i) => (
           <li className="menu__list-item" key={i}>
             <NavLink
               activeClassName="menu__link--active"
-              className={navLinkclsx(childItemClassName)}
+              className={navLinkClassNames(childItemClassName)}
               {...childItemProps}
               onClick={props.onClick}
             />
@@ -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-theme-classic/src/theme/Tabs/index.js b/packages/docusaurus-theme-classic/src/theme/Tabs/index.js
@@ -26,7 +26,8 @@ function Tabs(props) {
     const relevantTabGroupChoice = tabGroupChoices[groupId];
     if (
       relevantTabGroupChoice != null &&
-      relevantTabGroupChoice !== selectedValue
+      relevantTabGroupChoice !== selectedValue &&
+      values.some((value) => value.value === relevantTabGroupChoice)
     ) {
       setSelectedValue(relevantTabGroupChoice);
     }

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

diff --git a/website/docs/installation.md b/website/docs/installation.md
@@ -123,7 +123,7 @@ npm install
 To check that that the update occurred successfully, run:
 
 ```bash npm2yarn
-npm docusaurus --version
+npx docusaurus --version
 ```
 
 You should see the correct version as output.

diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx
@@ -348,6 +348,36 @@ You may want choices of the same kind of tabs to sync with each other. For examp
   <TabItem value="mac">Use Command + V to paste.</TabItem>
 </Tabs>
 
+For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change.
+
+```jsx
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    {label: 'Windows', value: 'win'},
+    {label: 'macOS', value: 'mac'},
+    {label: 'Linux', value: 'linux'},
+  ]}>
+  <TabItem value="win">I am Windows.</TabItem>
+  <TabItem value="mac">I am macOS.</TabItem>
+  <TabItem value="linux">I am Linux.</TabItem>
+</Tabs>
+```
+
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    {label: 'Windows', value: 'win'},
+    {label: 'macOS', value: 'mac'},
+    {label: 'Linux', value: 'linux'},
+  ]}>
+  <TabItem value="win">I am Windows.</TabItem>
+  <TabItem value="mac">I am macOS.</TabItem>
+  <TabItem value="linux">I am Linux.</TabItem>
+</Tabs>
+
 ---
 
 Tab choices with different `groupId`s will not interfere with each other: