docs: add link from every category index page to the guide page (#7665)

website/docs/guides/docs/sidebar/items.md

@@ -230,29 +230,10 @@ With category links, clicking on a category can navigate you to another page.
 
 Use category links to introduce a category of documents.
 
+Autogenerated categories can use the [`_category_.yml`](./autogenerated.md#category-item-metadata) file to declare the link.
+
 :::
 
-#### 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 on 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/[categoryName]`.
@@ -287,6 +268,27 @@ Use `generated-index` links as a quick way to get an introductory document.
 
 :::
 
+#### 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 on the [i18n introduction page](../../../i18n/i18n-introduction.md).
+
 #### Embedding generated index in doc page {#embedding-generated-index-in-doc-page}
 
 You can embed the generated cards list in a normal doc page as well, as long as the doc is used as a category index page. To do so, you need to use the `DocCardList` component, paired with the `useCurrentSidebarCategory` hook.

website/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+import {useLayoutDoc} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
+import Translate from '@docusaurus/Translate';
+import DocCategoryGeneratedIndexPage from '@theme-original/DocCategoryGeneratedIndexPage';
+import type {Props} from '@theme/DocCategoryGeneratedIndexPage';
+
+import styles from './styles.module.css';
+
+function HintFooter() {
+  const docPath = useLayoutDoc('guides/docs/sidebar/items', undefined)?.path;
+  return (
+    <p className={styles.footerTip}>
+      <Translate
+        values={{
+          guideLink: (
+            <Link to={`${docPath}#category-link`}>
+              <Translate>the generated index page guide</Translate>
+            </Link>
+          ),
+        }}>
+        {'Want to implement the same page? Read {guideLink} to find out!'}
+      </Translate>
+    </p>
+  );
+}
+
+export default function DocCategoryGeneratedIndexPageWrapper(
+  props: Props,
+): JSX.Element {
+  return (
+    <>
+      <DocCategoryGeneratedIndexPage {...props} />
+      <HintFooter />
+    </>
+  );
+}

website/src/theme/DocCategoryGeneratedIndexPage/styles.module.css

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.footerTip {
+  font-size: 0.8rem;
+  margin-top: var(--ifm-paragraph-margin-bottom);
+}

website/versioned_docs/version-2.0.0-beta.21/guides/docs/sidebar/items.md

@@ -60,7 +60,7 @@ module.exports = {
 };
 ```
 
-If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page.
+If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` Markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page.
 
 :::note
 
@@ -230,29 +230,10 @@ With category links, clicking on a category can navigate you to another page.
 
 Use category links to introduce a category of documents.
 
+Autogenerated categories can use the [`_category_.yml`](./autogenerated.md#category-item-metadata) file to declare the link.
+
 :::
 
-#### 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 on 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/[categoryName]`.
@@ -287,6 +268,27 @@ Use `generated-index` links as a quick way to get an introductory document.
 
 :::
 
+#### 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 on the [i18n introduction page](../../../i18n/i18n-introduction.md).
+
 #### Embedding generated index in doc page {#embedding-generated-index-in-doc-page}
 
 You can embed the generated cards list in a normal doc page as well, as long as the doc is used as a category index page. To do so, you need to use the `DocCardList` component, paired with the `useCurrentSidebarCategory` hook.
@@ -404,8 +406,10 @@ You can express typical sidebar items without much customization more concisely
 
 An item with type `doc` can be simply a string representing its ID:
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Longhand">
+```
 
 ```js title="sidebars.js"
 module.exports = {
@@ -420,8 +424,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="Shorthand">
+```
 
 ```js title="sidebars.js"
 module.exports = {
@@ -433,8 +439,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```
 
 So it's possible to simplify the example above to:
 
@@ -472,8 +480,10 @@ module.exports = {
 
 A category item can be represented by an object whose key is its label, and the value is an array of subitems.
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Longhand">
+```
 
 ```js title="sidebars.js"
 module.exports = {
@@ -489,8 +499,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="Shorthand">
+```
 
 ```js title="sidebars.js"
 module.exports = {
@@ -504,8 +516,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```
 
 This permits us to simplify that example to:
 
@@ -553,8 +567,10 @@ Note how the two consecutive category shorthands are compressed into one object
 
 Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Before">
+```
 
 ```js title="sidebars.js"
 module.exports = {
@@ -572,8 +588,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="After">
+```
 
 ```js title="sidebars.js"
 module.exports = {
@@ -587,5 +605,7 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```