feat(v2): allow infinitely nested sidebar

[endiliey]

Motivation

continuation from #1811

Expect more PR on docs plugin probably this week as I try to make docs metadata more efficient later on.
fix #827 #868 #1182

• Support more than one level deep of nested sidebar.
• Add more detailed documentation of sidebar.
  https://deploy-preview-1812--docusaurus-2.netlify.com/docs/sidebar
  (We actually already allow external href, etc its just undocumented because i forgot)
• Add test

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

Try with docu v2 site

// sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'level 1',
      items: [
        'introduction',
        {
          type: 'category',
          label: 'level 2',
          items: [
            'contributing',
            {
              type: 'category',
              label: 'level 3',
              items: [
                'design-principles',
                {
                  type: 'category',
                  label: 'level 4',
                  items: [
                    'installation',
                    {
                      type: 'category',
                      label: 'deeper more more',
                      items: ['sidebar'],
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    },
  ],
};

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit e056ac2

https://deploy-preview-1812--docusaurus-2.netlify.com

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit e056ac2

https://deploy-preview-1812--docusaurus-preview.netlify.com

[yangshun]

Awesome work! I made some small nitpicky changes. Do we want to consider removing support for the object format and force an array format? Also, we can allow a simpler format for the most common use cases. If a 2nd index is present and it's an array, that item is a category and the values in the 2nd array are children of that category. This definitely makes us have more work to do but is less verbose and resembles the plugins/preset config. WDYT?

module.exports = {
  docs: [
    [
      'item', [
        'inner-foo',
        'inner-bar',
      ],
    ],
  ]
}

This would be a breaking change but it's one that's worth making IMO.

[yangshun]

Merging first, we can talk about new API in future.

[endiliey]

I personally dont mind but from another perspective I think its not a good idea to force array format as it is only a syntatic sugar. There has been many breaking changes already :( Note that there are versioned sidebar as well. Migration will be even more painful (eg: for RN). If we can have less breaking changes thats better

const old = {
  docs: [
    {
      type: 'category',
      label: 'level 1',
      items: [
        'introduction',
        'contributing',
      ]
    },
    {
      type: 'category',
      label: 'Guides',
      items: [
        'blog',
      ]
    },
  ]
};

const new = {
  docs: {
    'level 1': [
      'introduction',
      'contributing'
    ],
    'Guides': ['blog']
  }
}

Both old and new is equivalent. In fact, old (v1 syntax) is transformed to new through

docusaurus/packages/docusaurus-plugin-content-docs-legacy/src/sidebars.ts

Lines 90 to 115 in 1591128

	/**
	* Converts sidebars object to mapping to arrays of sidebar item objects
	*/
	function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
	return Object.entries(sidebars).reduce(
	(acc: Sidebar, [sidebarId, sidebar]) => {
	let normalizedSidebar: SidebarItemCategoryRaw[];
	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(item => normalizeCategory(item));
	return acc;
	},
	{},
	);
	}