Merge branch 'master' into feat-comment-code-highlight

facebook · Mar 25, 2020 · 49319b2 · 49319b2
2 parents 8d57f55 + 5e0d11d
commit 49319b2
Show file tree

Hide file tree

Showing 37 changed files with 630 additions and 244 deletions.
diff --git a/.watchmanconfig b/.watchmanconfig
@@ -0,0 +1 @@
+{}
diff --git a/jest.config.js b/jest.config.js
@@ -27,5 +27,5 @@ module.exports = {
   transform: {
     '^.+\\.[jt]sx?$': 'babel-jest',
   },
-  setupFiles: ['./jest/stylelint-rule-test.js'],
+  setupFiles: ['./jest/stylelint-rule-test.js', 'array-flat-polyfill'],
 };
diff --git a/packages/docusaurus-init/templates/classic/docs/doc1.md b/packages/docusaurus-init/templates/classic/docs/doc1.md
@@ -171,12 +171,32 @@ This line is also a separate paragraph, but... This line is only separated by a
 
 ## Admonitions
 
-:::note This is a note :::
+:::note
 
-:::tip This is a tip :::
+This is a note
 
-:::important This is important :::
+:::
 
-:::caution This is a caution :::
+:::tip
 
-:::warning This is a warning :::
+This is a tip
+
+:::
+
+:::important
+
+This is important
+
+:::
+
+:::caution
+
+This is a caution
+
+:::
+
+:::warning
+
+This is a warning
+
+:::
diff --git a/packages/docusaurus-init/templates/facebook/docs/doc1.md b/packages/docusaurus-init/templates/facebook/docs/doc1.md
@@ -171,12 +171,32 @@ This line is also a separate paragraph, but... This line is only separated by a
 
 ## Admonitions
 
-:::note This is a note :::
+:::note
 
-:::tip This is a tip :::
+This is a note
 
-:::important This is important :::
+:::
 
-:::caution This is a caution :::
+:::tip
 
-:::warning This is a warning :::
+This is a tip
+
+:::
+
+:::important
+
+This is important
+
+:::
+
+:::caution
+
+This is a caution
+
+:::
+
+:::warning
+
+This is a warning
+
+:::
diff --git a/packages/docusaurus-plugin-content-blog/package.json b/packages/docusaurus-plugin-content-blog/package.json
@@ -20,7 +20,7 @@
     "fs-extra": "^8.1.0",
     "globby": "^10.0.1",
     "loader-utils": "^1.2.3",
-    "lodash": "^4.17.15"
+    "lodash.kebabcase": "^4.1.1"
   },
   "peerDependencies": {
     "@docusaurus/core": "^2.0.0",

diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts
@@ -6,7 +6,7 @@
  */
 
 import fs from 'fs-extra';
-import _ from 'lodash';
+import kebabCase from 'lodash.kebabcase';
 import path from 'path';
 import {normalizeUrl, docuHash, aliasedSitePath} from '@docusaurus/utils';
 
@@ -167,7 +167,7 @@ export default function pluginContentBlog(
         // eslint-disable-next-line no-param-reassign
         blogPost.metadata.tags = tags.map(tag => {
           if (typeof tag === 'string') {
-            const normalizedTag = _.kebabCase(tag);
+            const normalizedTag = kebabCase(tag);
             const permalink = normalizeUrl([tagsPath, normalizedTag]);
             if (!blogTags[normalizedTag]) {
               blogTags[normalizedTag] = {

diff --git a/...us-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-shorthand.js b/...us-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-shorthand.js
@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  docs: [
+    {
+      'level 1': [
+        'a',
+        {
+          'level 2': [
+            {
+              'level 3': [
+                'c',
+                {
+                  'level 4': [
+                    'd',
+                    {
+                      'deeper more more': ['e'],
+                    },
+                  ],
+                },
+              ],
+            },
+            'f',
+          ],
+        },
+      ],
+    },
+  ],
+};
diff --git a/...saurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-invalid-item.json b/...saurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-invalid-item.json
diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts
@@ -24,6 +24,17 @@ describe('loadSidebars', () => {
     expect(result).toMatchSnapshot();
   });
 
+  test('sidebars shortand and longform lead to exact same sidebar', async () => {
+    const sidebarPath1 = path.join(fixtureDir, 'sidebars-category.js');
+    const sidebarPath2 = path.join(
+      fixtureDir,
+      'sidebars-category-shorthand.js',
+    );
+    const sidebar1 = loadSidebars([sidebarPath1]);
+    const sidebar2 = loadSidebars([sidebarPath2]);
+    expect(sidebar1).toEqual(sidebar2);
+  });
+
   test('sidebars with category but category.items is not an array', async () => {
     const sidebarPath = path.join(
       fixtureDir,
@@ -93,15 +104,6 @@ describe('loadSidebars', () => {
     );
   });
 
-  test('sidebars with invalid sidebar item', async () => {
-    const sidebarPath = path.join(fixtureDir, 'sidebars-invalid-item.json');
-    expect(() =>
-      loadSidebars([sidebarPath]),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"Unknown sidebar item \\"{\\"a\\":\\"b\\",\\"c\\":\\"d\\"}\\"."`,
-    );
-  });
-
   test('sidebars with unknown sidebar item type', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-unknown-type.json');
     expect(() =>

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/packages/docusaurus-plugin-content-docs/src/sidebars.ts
@@ -15,8 +15,28 @@ import {
   SidebarItemRaw,
   SidebarItemLink,
   SidebarItemDoc,
+  SidebarCategoryShorthandRaw,
 } from './types';
 
+function isCategoryShorthand(
+  item: SidebarItemRaw,
+): item is SidebarCategoryShorthandRaw {
+  return typeof item !== 'string' && !item.type;
+}
+
+/**
+ * Convert {category1: [item1,item2]} shorthand syntax to long-form syntax
+ */
+function normalizeCategoryShorthand(
+  sidebar: SidebarCategoryShorthandRaw,
+): SidebarItemCategoryRaw[] {
+  return Object.entries(sidebar).map(([label, items]) => ({
+    type: 'category',
+    label,
+    items,
+  }));
+}
+
 /**
  * Check that item contains only allowed keys.
  */
@@ -75,27 +95,29 @@ function assertIsLink(item: any): asserts item is SidebarItemLink {
  * Normalizes recursively item and all its children. Ensures that at the end
  * each item will be an object with the corresponding type.
  */
-function normalizeItem(item: SidebarItemRaw): SidebarItem {
+function normalizeItem(item: SidebarItemRaw): SidebarItem[] {
   if (typeof item === 'string') {
-    return {
-      type: 'doc',
-      id: item,
-    };
+    return [
+      {
+        type: 'doc',
+        id: item,
+      },
+    ];
   }
-  if (!item.type) {
-    throw new Error(`Unknown sidebar item "${JSON.stringify(item)}".`);
+  if (isCategoryShorthand(item)) {
+    return normalizeCategoryShorthand(item).flatMap(normalizeItem);
   }
   switch (item.type) {
     case 'category':
       assertIsCategory(item);
-      return {...item, items: item.items.map(normalizeItem)};
+      return [{...item, items: item.items.flatMap(normalizeItem)}];
     case 'link':
       assertIsLink(item);
-      return item;
+      return [item];
     case 'ref':
     case 'doc':
       assertIsDoc(item);
-      return item;
+      return [item];
     default:
       throw new Error(`Unknown sidebar item type: ${item.type}`);
   }
@@ -107,20 +129,11 @@ function normalizeItem(item: SidebarItemRaw): SidebarItem {
 function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
   return Object.entries(sidebars).reduce(
     (acc: Sidebar, [sidebarId, sidebar]) => {
-      let normalizedSidebar: SidebarItemRaw[];
-
-      if (!Array.isArray(sidebar)) {
-        // Convert sidebar to a more generic structure.
-        normalizedSidebar = Object.entries(sidebar).map(([label, items]) => ({
-          type: 'category',
-          label,
-          items,
-        }));
-      } else {
-        normalizedSidebar = sidebar;
-      }
-
-      acc[sidebarId] = normalizedSidebar.map(normalizeItem);
+      const normalizedSidebar: SidebarItemRaw[] = Array.isArray(sidebar)
+        ? sidebar
+        : normalizeCategoryShorthand(sidebar);
+
+      acc[sidebarId] = normalizedSidebar.flatMap(normalizeItem);
 
       return acc;
     },

diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts
@@ -55,6 +55,7 @@ export type SidebarItem =
 
 export type SidebarItemRaw =
   | string
+  | SidebarCategoryShorthandRaw
   | SidebarItemDoc
   | SidebarItemLink
   | SidebarItemCategoryRaw
@@ -63,13 +64,13 @@ export type SidebarItemRaw =
       [key: string]: any;
     };
 
+export interface SidebarCategoryShorthandRaw {
+  [sidebarCategory: string]: SidebarItemRaw[];
+}
+
 // Sidebar given by user that is not normalized yet. e.g: sidebars.json
 export interface SidebarRaw {
-  [sidebarId: string]:
-    | {
-        [sidebarCategory: string]: SidebarItemRaw[];
-      }
-    | SidebarItemRaw[];
+  [sidebarId: string]: SidebarCategoryShorthandRaw | SidebarItemRaw[];
 }
 
 export interface Sidebar {

diff --git a/packages/docusaurus-preset-classic/src/index.js b/packages/docusaurus-preset-classic/src/index.js
@@ -19,8 +19,7 @@ const addAdmonitions = pluginOptions => {
 
   const admonitionsOptions = {
     remarkPlugins: (pluginOptions.remarkPlugins || []).concat([
-      admonitions,
-      pluginOptions.admonitions || {},
+      [admonitions, pluginOptions.admonitions || {}],
     ]),
   };