feat(content-docs): displayed_sidebar front matter (#5782)

website/docs/guides/docs/sidebar.md

@@ -241,7 +241,7 @@ We have introduced three types of item types in the above example: `doc`, `categ
 - **[Link](#sidebar-item-link)**: link to any internal or external page
 - **[Category](#sidebar-item-category)**: creates a dropdown of sidebar items
 - **[Autogenerated](#sidebar-item-autogenerated)**: generate a sidebar slice automatically
-- **[\*Ref](#sidebar-association)**: link to a doc page, without associating it with the sidebar
+- **[\*Ref](#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation
 
 ### Doc: link to a doc {#sidebar-item-doc}
 
@@ -966,31 +966,49 @@ module.exports = {
 };
 ```
 
-How does Docusaurus know which sidebar to display when browsing `commonDoc`? Answer: it doesn't, and we don't guarantee which sidebar it will pick. In this case, in order to remove the ambiguity, you can use the special `ref` sidebar item type.
+How does Docusaurus know which sidebar to display when browsing `commonDoc`? Answer: it doesn't, and we don't guarantee which sidebar it will pick.
 
-The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't set the association. It only registers itself as a link but doesn't take part in generating navigation metadata. When [generating pagination](#generating-pagination) and displaying sidebar, `ref` items are completely ignored.
+When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contains a link to doc Y, and when browsing doc Y, sidebar X will be displayed. But sometimes, we want to break either implicit binding:
 
-So you can turn the sidebars above into:
+1. _How do I generate a link to doc Y in sidebar X without making sidebar X displayed on Y?_ For example, when I include doc Y in multiple sidebars as in the example above, and I want to explicitly tell Docusaurus to display one sidebar?
+2. _How do I make sidebar X displayed when browsing doc Y, but sidebar X shouldn't contain the link to Y?_ For example, when Y is a "doc home page" and the sidebar is purely used for navigation?
+
+Front matter option `displayed_sidebar` will forcibly set the sidebar association. For the same example, you can still use doc shorthands without any special configuration:
 
 ```js title="sidebars.js"
 module.exports = {
   tutorialSidebar: {
-    'Category A': [
-      'doc1',
-      'doc2',
-      // highlight-next-line
-      {type: 'ref', id: 'commonDoc'},
-    ],
+    'Category A': ['doc1', 'doc2'],
   },
-  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
+  apiSidebar: ['doc3', 'doc4'],
 };
 ```
 
-Now, although the link to `commonDoc` is still included in the `tutorialSidebar` sidebar, when browsing `commonDoc`, only `apiSidebar` can be possibly displayed.
+And then add a front matter:
+
+```md title="commonDoc.md"
+---
+displayed_sidebar: apiSidebar
+---
+```
+
+Which explicitly tells Docusaurus to display `apiSidebar` when browsing `commonDoc`. Using the same method, you can make sidebar X which doesn't contain doc Y appear on doc Y:
+
+```md title="home.md"
+---
+displayed_sidebar: tutorialSidebar
+---
+```
+
+Even when `tutorialSidebar` doesn't contain a link to `home`, it will still be displayed when viewing `home`.
+
+If you set `displayed_sidebar: null`, no sidebar will be displayed whatsoever on this page, and subsequently, no pagination either.
 
 ### Generating pagination {#generating-pagination}
 
-Docusaurus uses the sidebar to generate the "next" and "previous" pagination links at the bottom of each doc page. It strictly uses the sidebar that is displayed: if no sidebar is associated, no pagination is generated either.
+Docusaurus uses the sidebar to generate the "next" and "previous" pagination links at the bottom of each doc page. It strictly uses the sidebar that is displayed: if no sidebar is associated, it doesn't generate pagination either. However, the docs linked as "next" and "previous" are not guaranteed to display the same sidebar: they are included in this sidebar, but in their front matter, they may have a different `displayed_sidebar`.
+
+If a sidebar is displayed by setting `displayed_sidebar` front matter, and this sidebar doesn't contain the doc itself, no pagination is displayed.
 
 You can customize pagination with front matter `pagination_next` and `pagination_prev`. Consider this sidebar:
 
@@ -1021,6 +1039,33 @@ You can also disable displaying a pagination link with `pagination_next: null` o
 
 The pagination label by default is the sidebar label. You can use the front matter `pagination_label` to customize how this doc appears in the pagination.
 
+### The `ref` item {sidebar-item-ref}
+
+The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When [generating pagination](#generating-pagination) and [displaying sidebar](#sidebar-association), `ref` items are completely ignored.
+
+Consider this example:
+
+```js title="sidebars.js"
+module.exports = {
+  tutorialSidebar: {
+    'Category A': [
+      'doc1',
+      'doc2',
+      // highlight-next-line
+      {type: 'ref', id: 'commonDoc'},
+      'doc5',
+    ],
+  },
+  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
+};
+}
+```
+
+You can think of the `ref` type as the equivalent to doing the following:
+
+- Setting `displayed_sidebar: tutorialSidebar` for `commonDoc` (`ref` is ignored in sidebar association)
+- Setting `pagination_next: doc5` for `doc2` and setting `pagination_prev: doc2` for `doc5` (`ref` is ignored in pagination generation)
+
 ## Passing custom props {#passing-custom-props}
 
 To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items: