feat(content-docs): sidebar category linking to document or auto-generated index page (#5830)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: Armano <armano2@users.noreply.github.com>
Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>

website/docs/guides/docs/sidebar.md

@@ -1,7 +1,7 @@
 ---
 id: sidebar
 title: Sidebar
-toc_max_heading_level: 4
+toc_max_heading_level: 5
 slug: /sidebar
 ---
 
@@ -290,6 +290,7 @@ type SidebarItemCategory = {
   // Category options:
   collapsible: boolean; // Set the category to be collapsible
   collapsed: boolean; // Set the category to be initially collapsed or open by default
+  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
 };
 ```
 
@@ -335,6 +336,69 @@ module.exports = {
 
 :::
 
+#### Category links {#category-link}
+
+With category links, clicking on a category can navigate you to another page.
+
+:::tip
+
+Use category links to introduce a category of documents.
+
+:::
+
+##### Doc link {#category-doc-link}
+
+A category can link to an existing document.
+
+```js title="sidebars.js"
+module.exports = {
+  docs: [
+    {
+      type: 'category',
+      label: 'Guides',
+      // highlight-start
+      link: {type: 'doc', id: 'introduction'},
+      // highlight-end
+      items: ['pages', 'docs', 'blog', 'search'],
+    },
+  ],
+};
+```
+
+See it in action in the [i18n introduction page](../../i18n/i18n-introduction.md).
+
+##### Generated index page {#generated-index-page}
+
+You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/{{category name}}`.
+
+```js title="sidebars.js"
+module.exports = {
+  docs: [
+    {
+      type: 'category',
+      label: 'Guides',
+      // highlight-start
+      link: {
+        type: 'generated-index',
+        title: 'Docusaurus Guides',
+        description: 'Learn about the most important Docusaurus concepts!',
+        slug: '/category/docusaurus-guides',
+      },
+      // highlight-end
+      items: ['pages', 'docs', 'blog', 'search'],
+    },
+  ],
+};
+```
+
+See it in action in the [Docusaurus Guides pages](/docs/next/category/guides).
+
+:::tip
+
+Use `generated-index` links as a quick way to get an introductory document.
+
+:::
+
 #### Collapsible categories {#collapsible-categories}
 
 We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.
@@ -499,13 +563,46 @@ module.exports = {
 };
 ```
 
+#### Category index convention {#category-index-convention}
+
+Docusaurus can automatically link a category to its index document.
+
+A category index document is a document following one of those filename conventions:
+
+- Named as `index` (case-insensitive): `docs/Guides/index.md`
+- Named as `README` (case-insensitive): `docs/Guides/README.mdx`
+- Same name as parent folder: `docs/Guides/Guides.md`
+
+This is equivalent to using a category with a [doc link](#category-doc-link):
+
+```js title="sidebars.js"
+module.exports = {
+  docs: [
+    // highlight-start
+    {
+      type: 'category',
+      label: 'Guides',
+      link: {type: 'doc', id: 'Guides/index'},
+      items: [],
+    },
+    // highlight-end
+  ],
+};
+```
+
+:::tip
+
+Naming your introductory document `README.md` makes it show up when browsing the folder using the GitHub interface, while using `index.md` makes the behavior more in line with how HTML files are served.
+
+:::
+
 #### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
 
 By default, the sidebar slice will be generated in **alphabetical order** (using files and folders names).
 
 If the generated sidebar does not look good, you can assign additional metadata to docs and categories.
 
-**For docs**: use additional frontmatter:
+**For docs**: use additional front matter:
 
 ```md title="docs/tutorials/tutorial-easy.md" {1-4}
 ---
@@ -524,10 +621,22 @@ This is the easy tutorial!
 {
   "label": "Tutorial",
   "position": 3,
-  "className": "red"
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Tutorial overview"
+  }
 }
 ```
 
+:::info
+
+If the `link` is explicitly specified, Docusaurus will not apply any [default conventions](#category-index-convention).
+
+The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist.
+
+:::
+
 ```yaml title="docs/tutorials/_category_.yml"
 label: 'Tutorial'
 position: 2.5 # float position is supported