From 9b77d29a704db02a83876daadfa71da817547f4d Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 23 Jun 2022 16:38:56 +0800 Subject: [PATCH 1/2] docs: add link from every category index page to the guide page --- website/docs/guides/docs/sidebar/items.md | 44 +++++++------ .../DocCategoryGeneratedIndexPage/index.tsx | 38 +++++++++++ .../styles.module.css | 11 ++++ .../guides/docs/sidebar/items.md | 64 ++++++++++++------- 4 files changed, 114 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..1124d31ad3d9 --- /dev/null +++ b/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx @@ -0,0 +1,38 @@ +/** + * 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'; + +export default function DocCategoryGeneratedIndexPageWrapper( + props: Props, +): JSX.Element { + 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!'} + +

+ + ); +} 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 +``` From 72003e78b13fc10793f79013d7eca0e98af0cb89 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 23 Jun 2022 18:22:50 +0800 Subject: [PATCH 2/2] refactor --- .../DocCategoryGeneratedIndexPage/index.tsx | 32 +++++++++++-------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx b/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx index 1124d31ad3d9..a407d9e4a2dc 100644 --- a/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx +++ b/website/src/theme/DocCategoryGeneratedIndexPage/index.tsx @@ -14,25 +14,31 @@ 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 { - 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!'} - -

+ ); }