mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-07 07:21:17 +08:00
35d30d2914
e.g. `./api/main-config-typescript.mdx` -> `./api/main-config/main-config-typescript.mdx`
102 lines
3.7 KiB
Plaintext
102 lines
3.7 KiB
Plaintext
---
|
||
title: 'Description'
|
||
sidebar:
|
||
order: 5
|
||
title: Description
|
||
---
|
||
|
||
<YouTubeCallout id="uAA1JvLcl-w" title="Avoid Documentation Nightmares with Storybook's Description Doc Block" params="start=84" />
|
||
|
||
The `Description` block displays the description for a component, story, or meta, obtained from their respective JSDoc comments.
|
||
|
||
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
```md
|
||
{/* ButtonDocs.mdx */}
|
||
|
||
import { Meta, Description } from '@storybook/blocks';
|
||
import * as ButtonStories from './Button.stories';
|
||
|
||
<Meta of={ButtonStories} />
|
||
|
||
<Description of={ButtonStories.Primary} />
|
||
```
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
## Description
|
||
|
||
```js
|
||
import { Description } from '@storybook/blocks';
|
||
```
|
||
|
||
`Description` is configured with the following props:
|
||
|
||
### `of`
|
||
|
||
Type: Story export or CSF file exports
|
||
|
||
Specifies where to pull the description from. It can either point to a story or a meta, depending on which description you want to show.
|
||
|
||
Descriptions are pulled from the JSDoc comments or parameters, and they are rendered as markdown. See [Writing descriptions](#writing-descriptions) for more details.
|
||
|
||
## Writing descriptions
|
||
|
||
There are multiple places to write the description of a component/story, depending on what you want to achieve. Descriptions can be written at the story level to describe each story of a component, or they can be written at the meta or component level to describe the component in general.
|
||
|
||
Descriptions can be written as [JSDoc comments](https://jsdoc.app/about-getting-started.html) above stories, meta, or components. Alternatively they can also be specified in [`parameters`](../../writing-stories/parameters.mdx). To describe a story via parameters instead of comments, add it to `parameters.docs.description.story`; to describe meta/component, add it to `parameters.docs.description.component`.
|
||
|
||
We recommend using JSDoc comments for descriptions, and only use the `parameters.docs.description.X` properties in situations where comments are not possible to write for some reason, or where you want the description shown in Storybook to be different from the comments. Comments provide a better writing experience as you don’t have to worry about indentation, and they are more discoverable for other developers that are exploring the story/component sources.
|
||
|
||
When documenting a story, reference a story export in the `of` prop (see below) and the Description block will look for descriptions in the following order:
|
||
|
||
1. `parameters.docs.description.story` in the story
|
||
2. JSDoc comments above the story
|
||
|
||
When documenting a component, reference a meta export in the `of` prop (see below) and the Description block will look for descriptions in the following order:
|
||
|
||
1. `parameters.docs.description.component` in the meta
|
||
2. JSDoc comments above the meta
|
||
3. JSDoc comments above the component
|
||
|
||
This flow gives you powerful ways to override the description for each scenario. Take the following example:
|
||
|
||
```jsx
|
||
// Button.jsx
|
||
|
||
/**
|
||
* # The Button component
|
||
* Shows a button
|
||
*/
|
||
export const Button = () => <button>Click me</button>;
|
||
```
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="api-doc-block-description-example.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
```md
|
||
{/* ButtonDocs.mdx */}
|
||
|
||
import { Meta, Description } from '@storybook/blocks';
|
||
import * as ButtonStories from './Button.stories';
|
||
|
||
<Meta of={ButtonStories} />
|
||
|
||
{/* Shows the description for the default export (the meta).
|
||
If that didn't have any comments, it would show the
|
||
comments from the component instead */}
|
||
<Description of={ButtonStories} />
|
||
|
||
{/* Shows the description for the Primary export */}
|
||
<Description of={ButtonStories.Primary} />
|
||
```
|
||
|
||
{/* prettier-ignore-end */}
|