feat(v2): allow non sidebar category to be first item of sidebar (#2032)

* feat(v2): allow non sidebar category to be first item of sidebar

* better error messages

* edit the react component

* Update website/docs/sidebar.md

* nits

* add @babel/plugin-transform-runtime

package.json

@@ -23,10 +23,10 @@
  "tsc": "lerna run tsc --no-private"
  },
  "devDependencies": {
- "@babel/core": "^7.7.2",
- "@babel/plugin-proposal-nullish-coalescing-operator": "^7.4.4",
- "@babel/plugin-proposal-optional-chaining": "^7.6.0",
- "@babel/preset-typescript": "^7.7.2",
+ "@babel/core": "^7.7.4",
+ "@babel/plugin-proposal-nullish-coalescing-operator": "^7.7.4",
+ "@babel/plugin-proposal-optional-chaining": "^7.7.4",
+ "@babel/preset-typescript": "^7.7.4",
  "@types/express": "^4.17.1",
  "@types/fs-extra": "^8.0.1",
  "@types/inquirer": "^6.5.0",

packages/docusaurus-1.x/package.json

@@ -26,15 +26,15 @@
  "docusaurus-rename-version": "./lib/rename-version.js"
  },
  "dependencies": {
- "@babel/core": "^7.7.2",
- "@babel/plugin-proposal-class-properties": "^7.7.0",
- "@babel/plugin-proposal-object-rest-spread": "^7.6.2",
+ "@babel/core": "^7.7.4",
+ "@babel/plugin-proposal-class-properties": "^7.7.4",
+ "@babel/plugin-proposal-object-rest-spread": "^7.7.4",
  "@babel/polyfill": "^7.7.0",
- "@babel/preset-env": "^7.7.1",
- "@babel/preset-react": "^7.7.0",
- "@babel/register": "^7.7.0",
- "@babel/traverse": "^7.7.2",
- "@babel/types": "^7.7.2",
+ "@babel/preset-env": "^7.7.4",
+ "@babel/preset-react": "^7.7.4",
+ "@babel/register": "^7.7.4",
+ "@babel/traverse": "^7.7.4",
+ "@babel/types": "^7.7.4",
  "autoprefixer": "^9.7.2",
  "babylon": "^6.18.0",
  "chalk": "^3.0.0",

packages/docusaurus-mdx-loader/package.json

@@ -8,8 +8,8 @@
  },
  "license": "MIT",
  "dependencies": {
- "@babel/parser": "^7.7.3",
- "@babel/traverse": "^7.7.2",
+ "@babel/parser": "^7.7.4",
+ "@babel/traverse": "^7.7.4",
  "@mdx-js/mdx": "^1.5.1",
  "@mdx-js/react": "^1.5.1",
  "github-slugger": "^1.2.1",

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-label.json

@@ -0,0 +1,11 @@
+{
+ "docs": {
+ "Test": [
+ {
+ "type": "category",
+ "label": true,
+ "items": ["doc1"]
+ }
+ ]
+ }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-doc-id-not-string.json

@@ -0,0 +1,10 @@
+{
+ "docs": {
+ "Test": [
+ {
+ "type": "doc",
+ "id": ["doc1"]
+ }
+ ]
+ }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-invalid-item.json

@@ -0,0 +1,8 @@
+{
+ "docs": [
+ {
+ "a": "b",
+ "c": "d"
+ }
+ ]
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-href.json

@@ -0,0 +1,11 @@
+{
+ "docs": {
+ "Test": [
+ {
+ "type": "link",
+ "label": "GitHub",
+ "href": ["example.com"]
+ }
+ ]
+ }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-label.json

@@ -0,0 +1,11 @@
+{
+ "docs": {
+ "Test": [
+ {
+ "type": "link",
+ "label": false,
+ "href": "https://github.com"
+ }
+ ]
+ }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-link.json

@@ -0,0 +1,11 @@
+{
+ "docs": {
+ "Test": [
+ {
+ "type": "link",
+ "label": "category",
+ "href": "https://github.com"
+ }
+ ]
+ }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap

@@ -1,5 +1,23 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`loadSidebars sidebars link 1`] = `
+Object {
+ "docs": Array [
+ Object {
+ "items": Array [
+ Object {
+ "href": "https://github.com",
+ "label": "category",
+ "type": "link",
+ },
+ ],
+ "label": "Test",
+ "type": "category",
+ },
+ ],
+}
+`;
+
 exports[`loadSidebars sidebars with deep level of category 1`] = `
 Object {
  "docs": Array [
@@ -57,6 +75,27 @@ Object {
 }
 `;
 
+exports[`loadSidebars sidebars with first level not a category 1`] = `
+Object {
+ "docs": Array [
+ Object {
+ "items": Array [
+ Object {
+ "id": "greeting",
+ "type": "doc",
+ },
+ ],
+ "label": "Getting Started",
+ "type": "category",
+ },
+ Object {
+ "id": "api",
+ "type": "doc",
+ },
+ ],
+}
+`;
+
 exports[`loadSidebars sidebars with known sidebar item type 1`] = `
 Object {
  "docs": Array [

packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts

@@ -32,7 +32,31 @@ describe('loadSidebars', () => {
  expect(() =>
  loadSidebars([sidebarPath]),
  ).toThrowErrorMatchingInlineSnapshot(
- `"Error loading \\"Category Label\\" category. Category items must be array."`,
+ `"Error loading {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}. \\"items\\" must be an array."`,
+ );
+ });
+
+ test('sidebars with category but category label is not a string', async () => {
+ const sidebarPath = path.join(
+ fixtureDir,
+ 'sidebars-category-wrong-label.json',
+ );
+ expect(() =>
+ loadSidebars([sidebarPath]),
+ ).toThrowErrorMatchingInlineSnapshot(
+ `"Error loading {\\"type\\":\\"category\\",\\"label\\":true,\\"items\\":[\\"doc1\\"]}. \\"label\\" must be a string."`,
+ );
+ });
+
+ test('sidebars item doc but id is not a string', async () => {
+ const sidebarPath = path.join(
+ fixtureDir,
+ 'sidebars-doc-id-not-string.json',
+ );
+ expect(() =>
+ loadSidebars([sidebarPath]),
+ ).toThrowErrorMatchingInlineSnapshot(
+ `"Error loading {\\"type\\":\\"doc\\",\\"id\\":[\\"doc1\\"]}. \\"id\\" must be a string."`,
  );
  });
 
@@ -41,10 +65,40 @@ describe('loadSidebars', () => {
  fixtureDir,
  'sidebars-first-level-not-category.js',
  );
+ const result = loadSidebars([sidebarPath]);
+ expect(result).toMatchSnapshot();
+ });
+
+ test('sidebars link', async () => {
+ const sidebarPath = path.join(fixtureDir, 'sidebars-link.json');
+ const result = loadSidebars([sidebarPath]);
+ expect(result).toMatchSnapshot();
+ });
+
+ test('sidebars link wrong label', async () => {
+ const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-label.json');
+ expect(() =>
+ loadSidebars([sidebarPath]),
+ ).toThrowErrorMatchingInlineSnapshot(
+ `"Error loading {\\"type\\":\\"link\\",\\"label\\":false,\\"href\\":\\"https://github.com\\"}. \\"label\\" must be a string."`,
+ );
+ });
+
+ test('sidebars link wrong href', async () => {
+ const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-href.json');
+ expect(() =>
+ loadSidebars([sidebarPath]),
+ ).toThrowErrorMatchingInlineSnapshot(
+ `"Error loading {\\"type\\":\\"link\\",\\"label\\":\\"GitHub\\",\\"href\\":[\\"example.com\\"]}. \\"href\\" must be a string."`,
+ );
+ });
+
+ test('sidebars with invalid sidebar item', async () => {
+ const sidebarPath = path.join(fixtureDir, 'sidebars-invalid-item.json');
  expect(() =>
  loadSidebars([sidebarPath]),
  ).toThrowErrorMatchingInlineSnapshot(
- `"Error loading {\\"type\\":\\"doc\\",\\"id\\":\\"api\\"}. First level item of a sidebar must be a category"`,
+ `"Unknown sidebar item \\"{\\"a\\":\\"b\\",\\"c\\":\\"d\\"}\\"."`,
  );
  });
 

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -25,16 +25,16 @@ import {
  LoadedContent,
  SourceToPermalink,
  PermalinkToSidebar,
- DocsSidebarItemCategory,
  SidebarItemLink,
  SidebarItemDoc,
- SidebarItemCategory,
  DocsSidebar,
  DocsBaseMetadata,
  MetadataRaw,
  DocsMetadataRaw,
  Metadata,
  VersionToSidebars,
+ SidebarItem,
+ DocsSidebarItem,
 } from './types';
 import {Configuration} from 'webpack';
 import {docsVersion} from './version';
@@ -237,32 +237,24 @@ export default function pluginContentDocs(
  };
  };
 
- const normalizeCategory = (
- category: SidebarItemCategory,
- ): DocsSidebarItemCategory => {
- const items = category.items.map(item => {
- switch (item.type) {
- case 'category':
- return normalizeCategory(item as SidebarItemCategory);
- case 'ref':
- case 'doc':
- return convertDocLink(item as SidebarItemDoc);
- case 'link':
- default:
- break;
- }
- return item as SidebarItemLink;
- });
- return {...category, items};
+ const normalizeItem = (item: SidebarItem): DocsSidebarItem => {
+ switch (item.type) {
+ case 'category':
+ return {...item, items: item.items.map(normalizeItem)};
+ case 'ref':
+ case 'doc':
+ return convertDocLink(item);
+ case 'link':
+ default:
+ return item;
+ }
  };
 
  // Transform the sidebar so that all sidebar item will be in the form of 'link' or 'category' only
  // This is what will be passed as props to the UI component
  const docsSidebars: DocsSidebar = Object.entries(loadedSidebars).reduce(
- (acc: DocsSidebar, [sidebarId, sidebarItemCategories]) => {
- acc[sidebarId] = sidebarItemCategories.map(sidebarItemCategory =>
- normalizeCategory(sidebarItemCategory),
- );
+ (acc: DocsSidebar, [sidebarId, sidebarItems]) => {
+ acc[sidebarId] = sidebarItems.map(normalizeItem);
  return acc;
  },
  {},