mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-07 05:31:05 +08:00
348 lines
11 KiB
Markdown
348 lines
11 KiB
Markdown
---
|
||
title: 'Doc Blocks'
|
||
---
|
||
|
||
<div>
|
||
TODO: vet the canvas changes. Originally it was Preview and now it's Canvas (associated issue https://github.com/storybookjs/storybook/issues/11696)
|
||
</div>
|
||
|
||
Doc Blocks are the building blocks of Storybook documentation pages. By default, [DocsPage](./docs-page.md) uses a combination of the blocks below to build a page for each of your components automatically.
|
||
|
||
Custom [addons](../configure/user-interface.md#storybook-addons) can also provide their own doc blocks.
|
||
|
||
## ArgsTable
|
||
|
||
Storybook Docs automatically generates component args tables for components in supported frameworks. These tables list the arguments ([args for short](../writing-stories/args.md)) of the component, and even integrate with [controls](../essentials/controls.md) to allow you to change the args of the currently rendered story.
|
||
|
||
<video autoPlay muted playsInline loop>
|
||
<source
|
||
src="addon-controls-docs-optimized.mp4"
|
||
type="video/mp4"
|
||
/>
|
||
</video>
|
||
|
||
This is extremely useful, but it can be further expanded. Additional information can be added to the component to better document it:
|
||
|
||
```js
|
||
// Button.js
|
||
|
||
import React from 'react';
|
||
import PropTypes from 'prop-types';
|
||
|
||
export default function Button({ isDisabled, content }) {
|
||
return <button disabled={isDisabled}>{content}</button>;
|
||
}
|
||
|
||
Button.propTypes = {
|
||
/**
|
||
Checks if the button should be disable
|
||
*/
|
||
isDisabled: PropTypes.bool.isRequired,
|
||
/**
|
||
The display content of the button
|
||
*/
|
||
content: PropTypes.string.isRequired,
|
||
};
|
||
```
|
||
|
||
By including the additional information, the args table will be updated. Offering a richer experience for any stakeholders involved.
|
||
|
||
### DocsPage
|
||
|
||
To use the `ArgsTable` in [DocsPage](./docs-page.md#component-parameter), export a component property on your stories metadata:
|
||
|
||
```js
|
||
// MyComponent.stories.js
|
||
|
||
import { MyComponent } from './MyComponent';
|
||
|
||
export default {
|
||
title: 'MyComponent',
|
||
component: MyComponent,
|
||
};
|
||
// your templates and stories
|
||
```
|
||
|
||
### MDX
|
||
|
||
To use the `ArgsTable` in MDX, use the Props block:
|
||
|
||
```js
|
||
// MyComponent.stories.mdx
|
||
|
||
import { Props } from '@storybook/addon-docs/blocks';
|
||
import { MyComponent } from './MyComponent';
|
||
|
||
# My Component!
|
||
|
||
<Props of={MyComponent} />
|
||
```
|
||
|
||
### Customizing
|
||
|
||
`ArgsTables` are automatically inferred from your components and stories, but sometimes it's useful to customize the results.
|
||
|
||
`ArgsTables` are rendered from an internal data structure called [ArgTypes](../api/mdx.md#argtypes). When you declare a story's component metadata, Docs automatically extracts ArgTypes based on the component's properties.
|
||
|
||
You can customize what's shown in the `ArgsTable` by customizing the `ArgTypes` data. This is currently available for [DocsPage](./docs-page.md) and `<Props story="xxx">` construct, but not for the `<Props of={component} />` construct.
|
||
|
||
<div class="aside">
|
||
|
||
NOTE: This API is experimental and may change outside of the typical semver release cycle
|
||
|
||
</div>
|
||
|
||
The API documentation of `ArgTypes` is detailed in a [separate section](../api/mdx.md#argtypes), but to control the description and default values, use the following fields:
|
||
|
||
| Field | Description |
|
||
| :----------------------------- | :----------------------------------------------------------------------------------------------: |
|
||
| **name** | The name of the property |
|
||
| **type.required** | The stories to be show, ordered by supplied name |
|
||
| **description** | A Markdown description for the property |
|
||
| **table.type.summary** | A short version of the type |
|
||
| **table.type.detail** | A short version of the type |
|
||
| **table.defaultValue.summary** | A short version of the type |
|
||
| **table.defaultValue.detail** | A short version of the type |
|
||
| **control** | See [addon-controls README ](https://github.com/storybookjs/storybook/tree/next/addons/controls) |
|
||
|
||
For instance:
|
||
|
||
```js
|
||
export default {
|
||
title: 'Button',
|
||
component: Button,
|
||
argTypes: {
|
||
label: {
|
||
description: 'overwritten description',
|
||
table: {
|
||
type: {
|
||
summary: 'something short',
|
||
detail: 'something really really long',
|
||
},
|
||
},
|
||
control: {
|
||
type: null,
|
||
},
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
This would render a row with a modified description, a type display with a dropdown that shows the detail, and no control.
|
||
|
||
If you find yourself writing the same definition over and over again, Storybook provides some convenient shorthands, that help you streamline your work.
|
||
|
||
For instance you can use:
|
||
|
||
- `number`, which is shorthand for `type: {name: 'number'}`
|
||
- `radio`, which is a shorhand for `control: {type: 'radio' }`
|
||
|
||
#### MDX
|
||
|
||
To customize `argTypes` in MDX, you can set an `mdx` prop on the `Meta` or `Story` components:
|
||
|
||
```js
|
||
|
||
<Meta
|
||
title="MyComponent"
|
||
component={MyComponent}
|
||
argTypes={{
|
||
label: {
|
||
name: 'label',
|
||
/* other argtypes required */
|
||
},
|
||
}}
|
||
/>
|
||
|
||
<Story name="some story" argTypes={{
|
||
label: {
|
||
name: 'different label',
|
||
/* other required data */
|
||
}
|
||
}}>
|
||
{/* story contents */}
|
||
</Story>
|
||
```
|
||
|
||
### Controls
|
||
|
||
The controls inside an `ArgsTable` are configured in exactly the same way as the [controls](../essentials/controls.md) addon pane. In fact you’ll probably notice the table is very similar! It uses the same component and mechanism behind the scenes.
|
||
|
||
## Source
|
||
|
||
Storybook Docs displays a story’s source code using the `Source` block. The snippet has built-in syntax highlighting and can be copied with the click of a button.
|
||
|
||
|
||
|
||
### DocsPage
|
||
|
||
In DocsPage, the `Source` block appears automatically within each story’s [Canvas](#canvas) block.
|
||
|
||
To customize the source snippet that’s displayed for a story, set the `docs.source.code` parameter:
|
||
|
||
```js
|
||
|
||
export const CustomSource = () => Template.bind({});
|
||
|
||
CustomSource.parameters = {
|
||
docs: {
|
||
source: {
|
||
code: 'Some custom string here';
|
||
}
|
||
},
|
||
};
|
||
```
|
||
|
||
### MDX
|
||
|
||
You can also use the `Source` block in MDX. It accepts either a story ID or `code` snippet. Use the `language` for syntax highlighting.
|
||
|
||
```js
|
||
import { Source } from '@storybook/addon-docs/blocks';
|
||
import dedent from 'ts-dedent';
|
||
|
||
<Source
|
||
language="css"
|
||
code={dedent`
|
||
.container {
|
||
display: grid | inline-grid;
|
||
}
|
||
`}
|
||
/>;
|
||
```
|
||
|
||
## Description
|
||
|
||
Storybook Docs shows a component’s description extracted from the source code or based on a user-provided string.
|
||
|
||
|
||
|
||
### DocsPage
|
||
|
||
In DocsPage, a component’s description is shown at the top of the page. For [supported frameworks](https://github.com/storybookjs/storybook/tree/next/addons/docs#framework-support), the component description is automatically extracted from a docgen component above the component in its source code. It can also be set by the `docs.description` parameter.
|
||
|
||
```js
|
||
|
||
export default {
|
||
title: 'CustomDescription'
|
||
parameters: {
|
||
docs: {
|
||
description: {
|
||
component: 'some component _markdown_'
|
||
}
|
||
},
|
||
}
|
||
};
|
||
|
||
export const WithStoryDescription = Template.bind({});
|
||
WithStoryDescription.parameters = {
|
||
docs: {
|
||
description: {
|
||
story: 'some story **markdown**'
|
||
}
|
||
},
|
||
};
|
||
```
|
||
|
||
### MDX
|
||
|
||
In MDX, the `Description` shows the component’s description using the same heuristics as the DocsPage. It also accepts a `markdown` parameter to show any user-provided Markdown string.
|
||
|
||
```js
|
||
|
||
import { Description } from '@storybook/addon-docs/blocks';
|
||
import dedent from 'ts-dedent';
|
||
import { Button } from './Button';
|
||
|
||
<Description of={Button} />
|
||
<Description markdown={dedent`
|
||
## Custom description
|
||
|
||
Insert fancy markdown here.
|
||
`}/>
|
||
```
|
||
|
||
## Story
|
||
|
||
Stories (component examples) are the basic building blocks in Storybook. In Storybook Docs, stories are rendered in the `Story` block.
|
||
|
||
|
||
|
||
### DocsPage
|
||
|
||
In DocsPage, a `Story` block is generated for each story in your [CSF](../api/csf.md) file, it's wrapped with a `Canvas` wrapper that gives it a toolbar on top (in the case of the first “primary” story) and a source code preview underneath.
|
||
|
||
### MDX
|
||
|
||
In MDX, the `Story` block is not only a way of displaying stories, but also the primary way to define them. Storybook looks for `Story` instances with the `name` prop, either defined at the top level of the document, or directly beneath a [Canvas](#canvas) block defined at the top level:
|
||
|
||
```js
|
||
import { Story } from '@storybook/addon-docs/blocks';
|
||
import { Button } from './Button';
|
||
|
||
export const Template = (args) => <Button {...args} />;
|
||
|
||
<Story name="Basic" args={{ label: ‘hello’ }}>
|
||
{Template.bind({})
|
||
</Story>
|
||
```
|
||
|
||
You can also reference existing stories in Storybook by ID:
|
||
|
||
```js
|
||
import { Story } from '@storybook/addon-docs/blocks';
|
||
|
||
<Story id="some-component--some-name" />;
|
||
```
|
||
|
||
### Inline rendering
|
||
|
||
In Storybook’s Canvas, all stories are rendered in the Preview iframe for isolated development. In Storybook Docs, when [inline rendering is supported by your framework](./docs-page.md#inline-stories-vs-iframe-stories), inline rendering is used by default for performance and convenience. However, you can force iframe rendering with `docs: { inlineStories: false }` parameter, or `inline={false}` in MDX.
|
||
|
||
## Canvas
|
||
|
||
Storybook Docs’ `Canvas` block is a wrapper that provides a toolbar for interacting with its contents, and also also provides [Source](#source) snippets automatically.
|
||
|
||
|
||
|
||
### DocsPage
|
||
|
||
In DocsPage, every story is wrapped in a `Canvas` block. The first story on the page is called the _primary_, and it has a toolbar. The other stories are also wrapped with `Canvas`, but there is no toolbar by default.
|
||
|
||
|
||
|
||
### MDX
|
||
|
||
In MDX, `Canvas` is more flexible: in addition to the DocsPage behavior, it can show multiple stories in one:
|
||
|
||
```js
|
||
import { Canvas } from '@storybook/addon-docs/blocks';
|
||
|
||
export const Template = (args) => <Badge {...args } />
|
||
|
||
<Preview>
|
||
<Story name="warning" args={{status: 'warning', label: 'Warning'}}>
|
||
{Template.bind({})}
|
||
</Story>
|
||
<Story name="neutral" args={{status: 'neutral', label: 'Neutral' }}>
|
||
{Template.bind({})}
|
||
</Story>
|
||
<Story name="error" args={{status: 'error', label: 'Error' }}>
|
||
{Template.bind({})}
|
||
</Story>
|
||
</Preview>
|
||
```
|
||
|
||
You can also place non-story content inside a `Canvas` block:
|
||
|
||
```js
|
||
import { Canvas } from '@storybook/addon-docs/blocks';
|
||
import { MyComponent } from './MyComponent';
|
||
<Preview>
|
||
<h2>Some here</h2>
|
||
<MyComponent />
|
||
</Preview>;
|
||
```
|
||
|
||
This renders the JSX content exactly as it would if you’d placed it directly in the MDX, but it also inserts the source snippet in a [Source](#source) block beneath the block.
|