feat(v2): enable subcategories (#1021)

* feat(v2): enable subcategories * nits * eslint issue https://github.com/prettier/prettier/issues/3734
2025-05-02 03:37:48 +02:00 · 2018-10-08 17:50:28 +08:00 · 2018-10-08 17:50:28 +08:00 · f62029c30e
commit f62029c30e
parent 954456088c
9 changed files with 150 additions and 43 deletions
--- a/v2/.eslintrc.js
+++ b/v2/.eslintrc.js
@ -9,7 +9,7 @@ module.exports = {
    jest: true,
    node: true,
  },
-  extends: ['airbnb', 'prettier'],
+  extends: ['airbnb', 'prettier', 'prettier/react'],
  rules: {
    'no-console': OFF,
    'func-names': OFF,
--- a/v2/lib/load/docs/metadata.js
+++ b/v2/lib/load/docs/metadata.js
@ -151,6 +151,7 @@ module.exports = async function processMetadata(
  if (order[id]) {
    metadata.sidebar = order[id].sidebar;
    metadata.category = order[id].category;
+    metadata.subCategory = order[id].subCategory;
    if (order[id].next) {
      metadata.next_id = order[id].next;
      metadata.next = (language ? `${language}-` : '') + order[id].next;
--- a/v2/lib/load/docs/order.js
+++ b/v2/lib/load/docs/order.js
@ -9,11 +9,26 @@ module.exports = function createOrder(allSidebars = {}) {

    let ids = [];
    const categoryOrder = [];
+    const subCategoryOrder = [];
    Object.keys(categories).forEach(category => {
-      ids = ids.concat(categories[category]);
-      // eslint-disable-next-line
-      for (let i = 0; i < categories[category].length; i++) {
-        categoryOrder.push(category);
+      if (Array.isArray(categories[category])) {
+        ids = ids.concat(categories[category]);
+
+        // eslint-disable-next-line
+        for (let i = 0; i < categories[category].length; i++) {
+          categoryOrder.push(category);
+          subCategoryOrder.push(undefined);
+        }
+      } else {
+        Object.keys(categories[category]).forEach(subCategory => {
+          ids = ids.concat(categories[category][subCategory]);
+
+          // eslint-disable-next-line
+          for (let i = 0; i < categories[category][subCategory].length; i++) {
+            categoryOrder.push(category);
+            subCategoryOrder.push(subCategory);
+          }
+        });
      }
    });

@ -29,6 +44,7 @@ module.exports = function createOrder(allSidebars = {}) {
        next,
        sidebar,
        category: categoryOrder[i],
+        subCategory: subCategoryOrder[i],
      };
    }
  });
--- a/v2/lib/theme/Sidebar/index.js
+++ b/v2/lib/theme/Sidebar/index.js
@ -12,37 +12,56 @@ function Sidebar(props) {
    return null;
  }
  const thisSidebar = docsSidebars[sidebar];
+
+  const renderItemLink = rawLinkID => {
+    const linkID = (language ? `${language}-` : '') + rawLinkID;
+    const linkMetadata = docsMetadatas[linkID];
+    if (!linkMetadata) {
+      throw new Error(
+        `Improper sidebars.json file, document with id '${linkID}' not found.`,
+      );
+    }
+    const activeItem = linkID === thisID;
+    return (
+      <li key={linkID}>
+        <Link
+          className={classnames(styles.sidebarLink, {
+            [styles.sidebarLinkActive]: activeItem,
+          })}
+          to={linkMetadata.permalink}>
+          {linkMetadata.sidebar_label || linkMetadata.title}
+        </Link>
+      </li>
+    );
+  };
+
+  const renderCategory = categoryName => {
+    const category = thisSidebar[categoryName];
+    return (
+      <div className={styles.sidebarGroup} key={categoryName}>
+        <h3 className={styles.sidebarGroupTitle}>{categoryName}</h3>
+        <ul className={styles.sidebarList}>
+          {Array.isArray(category)
+            ? category.map(renderItemLink)
+            : Object.keys(category).map(subCategoryName => (
+                <div className={styles.sidebarSubGroup} key={subCategoryName}>
+                  <h4 className={styles.sidebarSubGroupTitle}>
+                    {subCategoryName}
+                  </h4>
+                  <ul className={styles.sidebarList}>
+                    {category[subCategoryName].map(renderItemLink)}
+                  </ul>
+                </div>
+              ))}
+        </ul>
+      </div>
+    );
+  };
+
  return (
    thisSidebar && (
      <div className={styles.sidebar}>
-        {Object.keys(thisSidebar).map(categoryName => (
-          <div className={styles.sidebarGroup} key={categoryName}>
-            <h3 className={styles.sidebarGroupTitle}>{categoryName}</h3>
-            <ul className={styles.sidebarList}>
-              {thisSidebar[categoryName].map(rawLinkID => {
-                const linkID = (language ? `${language}-` : '') + rawLinkID;
-                const linkMetadata = docsMetadatas[linkID];
-                if (!linkMetadata) {
-                  throw new Error(
-                    `Improper sidebars.json file, document with id '${linkID}' not found.`,
-                  );
-                }
-                const activeItem = linkID === thisID;
-                return (
-                  <li key={linkID}>
-                    <Link
-                      className={classnames(styles.sidebarLink, {
-                        [styles.sidebarLinkActive]: activeItem,
-                      })}
-                      to={linkMetadata.permalink}>
-                      {linkMetadata.sidebar_label || linkMetadata.title}
-                    </Link>
-                  </li>
-                );
-              })}
-            </ul>
-          </div>
-        ))}
+        {Object.keys(thisSidebar).map(renderCategory)}
      </div>
    )
  );
--- a/v2/lib/theme/Sidebar/styles.css
+++ b/v2/lib/theme/Sidebar/styles.css
@ -7,7 +7,18 @@
  margin-bottom: 20px;
 }

+.sidebarSubGroup {
+  margin-top: 10px;
+  margin-left: 10px;
+}
+
+.sidebarSubGroupTitle {
+  font-size: 16px;
+  margin: 0;
+}
+
 .sidebarGroupTitle {
+  font-size: 18px;
  margin: 0;
 }

--- a/v2/package.json
+++ b/v2/package.json
@ -38,7 +38,7 @@
    "eslint-config-prettier": "^2.9.0",
    "eslint-plugin-import": "^2.12.0",
    "eslint-plugin-jsx-a11y": "^6.0.3",
-    "eslint-plugin-react": "^7.9.1",
+    "eslint-plugin-react": "^7.11.1",
    "jest": "^23.4.2",
    "prettier": "^1.13.7"
  },
--- a/v2/test/load/docs/order.test.js
+++ b/v2/test/load/docs/order.test.js
@ -1,7 +1,58 @@
 import createOrder from '@lib/load/docs/order';

 describe('createOrder', () => {
-  test('should populate docs index from multiple sidebars', () => {
+  test('multiple sidebars with subcategory', () => {
+    const result = createOrder({
+      docs: {
+        Category1: {
+          'Subcategory 1': ['doc1'],
+          'Subcategory 2': ['doc2'],
+        },
+        Category2: ['doc3', 'doc4'],
+      },
+      otherDocs: {
+        Category1: ['doc5'],
+      },
+    });
+    expect(result).toEqual({
+      doc1: {
+        category: 'Category1',
+        subCategory: 'Subcategory 1',
+        next: 'doc2',
+        previous: undefined,
+        sidebar: 'docs',
+      },
+      doc2: {
+        category: 'Category1',
+        subCategory: 'Subcategory 2',
+        next: 'doc3',
+        previous: 'doc1',
+        sidebar: 'docs',
+      },
+      doc3: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: 'doc4',
+        previous: 'doc2',
+        sidebar: 'docs',
+      },
+      doc4: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: undefined,
+        previous: 'doc3',
+        sidebar: 'docs',
+      },
+      doc5: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: undefined,
+        previous: undefined,
+        sidebar: 'otherDocs',
+      },
+    });
+  });
+  test('multiple sidebars without subcategory', () => {
    const result = createOrder({
      docs: {
        Category1: ['doc1', 'doc2'],
@ -14,30 +65,35 @@ describe('createOrder', () => {
    expect(result).toEqual({
      doc1: {
        category: 'Category1',
+        subCategory: undefined,
        next: 'doc2',
        previous: undefined,
        sidebar: 'docs',
      },
      doc2: {
        category: 'Category1',
+        subCategory: undefined,
        next: 'doc3',
        previous: 'doc1',
        sidebar: 'docs',
      },
      doc3: {
        category: 'Category2',
+        subCategory: undefined,
        next: 'doc4',
        previous: 'doc2',
        sidebar: 'docs',
      },
      doc4: {
        category: 'Category2',
+        subCategory: undefined,
        next: undefined,
        previous: 'doc3',
        sidebar: 'docs',
      },
      doc5: {
        category: 'Category1',
+        subCategory: undefined,
        next: undefined,
        previous: undefined,
        sidebar: 'otherDocs',
@ -45,7 +101,7 @@ describe('createOrder', () => {
    });
  });

-  test('should resolve docs from older versions', () => {
+  test('versioned sidebars', () => {
    const result = createOrder({
      docs: {
        Category1: ['doc1'],
@ -58,18 +114,21 @@ describe('createOrder', () => {
    expect(result).toEqual({
      doc1: {
        category: 'Category1',
+        subCategory: undefined,
        next: undefined,
        previous: undefined,
        sidebar: 'docs',
      },
      'version-1.2.3-doc1': {
        category: 'Category2',
+        subCategory: undefined,
        next: undefined,
        previous: 'version-1.2.3-doc2',
        sidebar: 'version-1.2.3-docs',
      },
      'version-1.2.3-doc2': {
        category: 'Category1',
+        subCategory: undefined,
        next: 'version-1.2.3-doc1',
        previous: undefined,
        sidebar: 'version-1.2.3-docs',
--- a/v2/website/sidebars.json
+++ b/v2/website/sidebars.json
@ -1,9 +1,9 @@
 {
  "docs": {
-    "Foo": [
-      "foo/bar",
-      "foo/baz"
-    ],
+    "Foo": {
+      "bar": ["foo/bar"],
+      "baz": ["foo/baz"]
+    },
    "Endi": [
      "docusaurus",
      "highlight",
--- a/v2/yarn.lock
+++ b/v2/yarn.lock
@ -2527,10 +2527,11 @@ eslint-plugin-jsx-a11y@^6.0.3:
    has "^1.0.3"
    jsx-ast-utils "^2.0.1"

-eslint-plugin-react@^7.9.1:
-  version "7.10.0"
-  resolved "https://registry.yarnpkg.com/eslint-plugin-react/-/eslint-plugin-react-7.10.0.tgz#af5c1fef31c4704db02098f9be18202993828b50"
+eslint-plugin-react@^7.11.1:
+  version "7.11.1"
+  resolved "https://registry.yarnpkg.com/eslint-plugin-react/-/eslint-plugin-react-7.11.1.tgz#c01a7af6f17519457d6116aa94fc6d2ccad5443c"
  dependencies:
+    array-includes "^3.0.3"
    doctrine "^2.1.0"
    has "^1.0.3"
    jsx-ast-utils "^2.0.1"