3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-30 06:50:36 +02:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Joshua Chen 2022-06-23 19:46:59 +08:00 • committed by GitHub
parent 42ab07f62f
commit 8e3e89d9ff
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 120 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

44
website/docs/guides/docs/sidebar/items.md
View file

@ -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.

44
website/src/theme/DocCategoryGeneratedIndexPage/index.tsx Normal file
View file

@ -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 />
</>
);
}

11
website/src/theme/DocCategoryGeneratedIndexPage/styles.module.css Normal file
View file

@ -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);
}

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

@ -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>
```