From 8e3e89d9ffa67b9c01d466096d9d5d51f1eea219 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 23 Jun 2022 19:46:59 +0800 Subject: [PATCH] docs: add link from every category index page to the guide page (#7665) --- website/docs/guides/docs/sidebar/items.md | 44 +++++++------ .../DocCategoryGeneratedIndexPage/index.tsx | 44 +++++++++++++ .../styles.module.css | 11 ++++ .../guides/docs/sidebar/items.md | 64 ++++++++++++------- 4 files changed, 120 insertions(+), 43 deletions(-) create mode 100644 website/src/theme/DocCategoryGeneratedIndexPage/index.tsx create mode 100644 website/src/theme/DocCategoryGeneratedIndexPage/styles.module.css diff --git a/website/docs/guides/docs/sidebar/items.md b/website/docs/guides/docs/sidebar/items.md index 6a67d8ee5898..fa7af72ca9be 100644 --- a/website/docs/guides/docs/sidebar/items.md +++ b/website/docs/guides/docs/sidebar/items.md @@ -230,28 +230,9 @@ With category links, clicking on a category can navigate you to another page. 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'], - }, - ], -}; -``` +Autogenerated categories can use the [`_category_.yml`](./autogenerated.md#category-item-metadata) file to declare the link. -See it in action on the [i18n introduction page](../../../i18n/i18n-introduction.md). +::: #### Generated index page {#generated-index-page} @@ -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. diff --git a/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx b/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx new file mode 100644 index 000000000000..a407d9e4a2dc --- /dev/null +++ b/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 ( +

+ + the generated index page guide + + ), + }}> + {'Want to implement the same page? Read {guideLink} to find out!'} + +

+ ); +} + +export default function DocCategoryGeneratedIndexPageWrapper( + props: Props, +): JSX.Element { + return ( + <> + + + + ); +} diff --git a/website/src/theme/DocCategoryGeneratedIndexPage/styles.module.css b/website/src/theme/DocCategoryGeneratedIndexPage/styles.module.css new file mode 100644 index 000000000000..a233ab72e7a5 --- /dev/null +++ b/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); +} diff --git a/website/versioned_docs/version-2.0.0-beta.21/guides/docs/sidebar/items.md b/website/versioned_docs/version-2.0.0-beta.21/guides/docs/sidebar/items.md index 04faf577a7e7..fa7af72ca9be 100644 --- a/website/versioned_docs/version-2.0.0-beta.21/guides/docs/sidebar/items.md +++ b/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,28 +230,9 @@ With category links, clicking on a category can navigate you to another page. Use category links to introduce a category of documents. -::: - -#### Doc link {#category-doc-link} - -A category can link to an existing document. +Autogenerated categories can use the [`_category_.yml`](./autogenerated.md#category-item-metadata) file to declare the link. -```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} @@ -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 +``` ```js title="sidebars.js" module.exports = { @@ -420,8 +424,10 @@ module.exports = { }; ``` +```mdx-code-block +``` ```js title="sidebars.js" module.exports = { @@ -433,8 +439,10 @@ module.exports = { }; ``` +```mdx-code-block +``` 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 +``` ```js title="sidebars.js" module.exports = { @@ -489,8 +499,10 @@ module.exports = { }; ``` +```mdx-code-block +``` ```js title="sidebars.js" module.exports = { @@ -504,8 +516,10 @@ module.exports = { }; ``` +```mdx-code-block +``` 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 +``` ```js title="sidebars.js" module.exports = { @@ -572,8 +588,10 @@ module.exports = { }; ``` +```mdx-code-block +``` ```js title="sidebars.js" module.exports = { @@ -587,5 +605,7 @@ module.exports = { }; ``` +```mdx-code-block +```