GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-05 08:01:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

initial commit for 6 0 migration of writing docs

Browse Source
This commit is contained in:
jonniebigodes 2020-07-23 00:25:01 +01:00
parent c4d119443a
commit a24f432aec
4 changed files with 802 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

370
docs/writing-docs/docs-blocks.md Normal file
View File

@ -0,0 +1,370 @@
---
title: 'Doc Blocks'
---
Doc Blocks are the building blocks of Storybook documentation pages. By default, [DocsPage](./docs-page) uses a combination of the below blocks to build a page for each of your components automatically.
<div style="background-color:#F8FAFC">
TODO: ask tom about both links below to where they should point to.
</div>
Also, custom [addons] can provide their own doc blocks, and there are [many available].
### ArgsTable
Storybook Docs automatically generates component props tables for components in supported frameworks. These tables list the [args](../writing-stories/args) of the component, and even integrate with [controls](../essentials/controls) to allow you to change the args of the currently rendered story.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (Use the same gif present in the SB 6.0 doc)
</div>
#### DocsPage
To use the ArgsTable in [DocsPage](./docspage#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 props table 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
Props tables are automatically inferred from your components and stories, but sometimes it's useful to customize the results.
<div style="background-color:#F8FAFC">
TODO: ask tom if links are accurate
</div>
Props tables are rendered from an internal data structure called [ArgTypes](../api/stories#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 props table by customizing the ArgTypes data. This is currently available for [DocsPage](locate-docs-page) and `<Props story="xxx">` construct, but not for the `<Props of={component} />` construct.
> NOTE: This API is experimental and may change outside of the typical semver release cycle
The API documentation of ArgTypes is detailed in a [separate section](../api/stories#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.
<div style="background-color:#F8FAFC">
TODO: ask tom about this and how we can improve.
My read on this is that we come from null that shows no control. But we have some shorthands that help the reader to show something.
Probably we could add this as a aside, or give it more emphasis
</div>
> Storybook provides shorthand for common tasks:
> type: 'number' is shorthand for type: { name: 'number' }
> control: 'radio' is shorthand 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 a props table are configured in exactly the same way as the [controls](../essentials/controls) 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.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
#### DocsPage
In DocsPage, the `Source` block appears automatically within each story’s [Preview] block.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
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 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.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
#### DocsPage
<div style="background-color:#F8FAFC">
TODO: left it for now ask feedback tom/shillman on this based on [pr](https://github.com/storybookjs/storybook/issues/11441)
</div>
In DocsPage, a component’s description is shown at the top of the page. For [supported frameworks], 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.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
```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] file, wrapped with a `Preview` wrapper that gives it a toolbar on top (in the case of the first “primary” story) and a source code preview underneath.
#### MDX
<div>
TODO: ask tom about Preview link for clarity.
</div>
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 [Preview](locate-preview) 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
<div>
TODO: ask tom/michael about the preview iframe. as we've been calling it canvas so far and now move to preview.
And also inline rendering support location
</div>
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](locate-link), 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.
### Preview
<div>
TODO: ask tom about Source link for clarity, as me i know that the source shows ad hoc the story file content. But another reader might not know.
</div>
Storybook Docs’ `Preview` block is a wrapper that provides a toolbar for interacting with its contents, and also also provides [Source](locate-source) snippets automatically.
<divs tyle="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
#### DocsPage
In DocsPage, every story is wrapped in a `Preview` block. The first story on the page is called the _primary_, and it has a toolbar. The other stories are also wrapped with `Previews`, but there is no toolbar by default.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
#### MDX
In MDX, `Preview` is more flexible: in addition to the DocsPage behavior, it can show multiple stories in one, and even show non-story content.
When you
```js
import { Preview } 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>
```
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>
You can also place non-story content inside a `Preview` block:
```js
import { Preview } from '@storybook/addon-docs/blocks';
import { MyComponent } from './MyComponent';
<Preview>
<h2>Some here</h2>
<MyComponent />
</Preview>
```
<div>
TODO: ask tom about Source link for clarity, as me i know that the source shows ad hoc the story file content. But another reader might not know.
</div>
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](locate-source) block beneath the block.
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (mention of a image in the SB 6.0 doc (needs to be vetted))
</div>

190
docs/writing-docs/docs-page.md Normal file
View File

@ -0,0 +1,190 @@
---
title: 'DocsPage'
---
When you install [Storybook Docs](https://github.com/storybookjs/storybook/blob/next/addons/docs/README.md), DocsPage is the zero-config default documentation that all stories get out of the box. It aggregates your stories, text descriptions, docgen comments, props tables, and code examples into a single page for each component.
The best practice for docs is for each component to have its own set of documentation and stories.
### Component parameter
Storybook uses the `component` key in the story file’s default export to extract the component's description and props.
```js
// Button.stories.js
import { Button } from './Button';
export default {
title: 'Storybook Examples/Button',
component: Button,
};
```
### Subcomponents parameter
Sometimes it's useful to document multiple components together. For example, a component library’s List and ListItem components might not make sense without one another.
DocsPage has the concept of a "primary" component that is defined by the `component` parameter. It also accepts one or more `subcomponents`.
```js
// List.stories.js
import { List, ListHeading, ListItem } from './List';
export default {
title: 'Path/to/List',
component: List,
subcomponents: { ListHeading, ListItem },
};
```
<div style="background-color:#F8FAFC">
TODO: add image per screenshot requirements (Image of subcomponents)
</div>
Subcomponent prop tables will show up in a tabbed interface along with the primary component. The tab titles will correspond to the keys of the subcomponents object.
If you want to organize your documentation differently for component groups, we recommend using MDX. It gives you complete control over display and supports any configuration.
### Replacing DocsPage
Replace DocsPage template with your own for the entire Storybook, a specific component, or a specific story.
Override the `docs.page` [parameter](../writing-stories/parameters):
- With null to remove docs.
- With MDX docs.
- With a custom component
#### Story-level
Override the `docs.page` [parameter](../writing-stories/parameters#story-parameters) in the story definition.
```js
// Button.stories.js
export const Primary = ButtonStory.bind({});
Primary.parameters = { docs: { page: null } }
```
#### Component-level
Override the `docs.page` [parameter](../writing-stories/parameters#component-parameters) in the default export of the story file.
```js
// Button.stories.js
import { Button } from './Button';
export default {
title: 'Storybook Examples/Button',
component: Button,
parameters: {
docs: {
page: null
}
},
};
```
#### Global-level
Override the `docs.page` [parameter](../writing-stories/parameters#global-parameters) in [`.storybook/preview.js`](../configure/overview#configure-story-rendering).
```js
// .storybook/preview.js
export const parameters { docs: { page: null } });
```
### Remixing DocsPage using doc blocks
Doc blocks are the basic building blocks of Storybook Docs. DocsPage composes them to provide a reasonable UI documentation experience out of the box.
If you want to make minor customizations to the default DocsPage but don’t want to write your own MDX you can remix DocsPage. That allows you to reorder, add, or omit doc blocks without losing Storybook’s automatic docgen capabilities.
Here's an example of rebuilding DocsPage for the Button component using doc blocks:
```js
// Button.stories.js
import React from 'react';
import {
Title,
Subtitle,
Description,
Primary,
Props,
Stories,
} from '@storybook/addon-docs/blocks';
import { Button } from './Button';
export default {
title: 'Components/Button',
component: Button,
parameters: {
docs: {
page: () => (
<>
<Title />
<Subtitle />
<Description />
<Primary />
<Props />
<Stories />
</>
),
},
},
};
```
Apply a similar technique to remix the DocsPage at the [story](#story-level), [component](#component-level), or [global](#global-level) level.
In addition, you can interleave your own components to customize the auto-generated contents of the page, or pass in different options to the blocks to customize their appearance. Read more about [Doc Blocks](./docs-blocks).
### Story file names
<div>
TODO ask tom/dom for a read on this. I went a bit of restructuring so that this page aligns with the mdx one in terms of wording/flow.
</div>
Unless you use a custom [webpack configuration](../configure/integration#extending-storybooks-webpack-config), all of your story files should have the suffix `*.stories.@(j|t)sx?`, e.g. "Badge.stories.js", "Badge.stories.tsx", etc. This tells Storybook and its docs preset to display the docs based on the file contents.
### Inline stories vs. Iframe stories
DocsPage displays all the stories of a component in one page. You have the option of rendering those stories inline or in an iframe.
By default, we render React and Vue stories inline. Stories from other supported frameworks will render in an `<iframe>`by default.
The iframe creates a clean separation between your code and Storybook’s UI. But using an iframe has disadvantages. You have to explicitly set the height of iframe stories or you’ll see a scroll bar. And certain dev tools might not work right.
Render your framework’s stories inline using two docs configuration options in tandem, `inlineStories` and `prepareForInline`.
Setting `inlineStories` to `true` tells Storybook to stop putting your stories in an iframe. The `prepareForInline` accepts a function that transforms story content from your given framework to something React can render (Storybook’s UI is built in React).
Different frameworks will need to approach this in different ways. Angular, for example, might convert its story content into a custom element (you can read about that here).
Here’s an example of how to render Vue stories inline. The following docs config block uses `prepareForInline` along with an effect hook provided by [@egoist/vue-to-react](https://github.com/egoist/vue-to-react).
```js
// .storybook/preview.js
import React from 'react';
import { render } from 'react-dom';
import toReact from '@egoist/vue-to-react';
export const parameters = {
docs: {
prepareForInline: (storyFn, { args }) => {
const Story = toReact(storyFn());
return <Story {...args} />;
},
},
};
```
With this function, anyone using the docs addon for [@storybook/vue](https://github.com/storybookjs/storybook/tree/master/app/vue) can make their stories render inline, either globally with the inlineStories docs parameter, or on a per-story-basis using the inline prop on the `<Story>` doc block.
If you come up with an elegant and flexible implementation for the prepareForInline function for your own framework, let us know. We'd love to make it the default configuration to make inline stories more accessible for a larger variety of frameworks!

24
docs/writing-docs/introduction.md Normal file
View File

@ -0,0 +1,24 @@
---
title: 'Introduction'
---
When you write component stories during development, you also create basic documentation to revisit later.
Storybook gives you tools to expand this basic documentation with prose and layout that feature your components and stories prominently. That allows you to create UI library usage guidelines, design system sites, and more.
<div style="background-color:#F8FAFC">
TODO: add image per screenshot requirements (Image of various SB docs sites)
</div>
Out of the box, Storybook ships with [DocsPage](./docs-page), a documentation template that lists all the stories for a component and associated metadata. It infers metadata values based on source code, types and JSDoc comments. [Customize](./docs-page#replacing-docspage) this page to create a new template if you have specific requirements.
You can also create free-form pages for each component using [MDX](./mdx), a format for simultaneously documenting components and writing stories.
In both cases, you’ll use [Doc Blocks](./docs-blocks) as the building blocks to create full featured documentation.
<div style="background-color:#F8FAFC">
TODO: ask tom if this is the proper place for the advanced
</div>
Docs is autoconfigured to work out of the box in most use cases. In some cases you may need or want to tweak the configuration. Read more about it in the [ADVANCED README](./docs-page#remixing-docspage-using-doc-blocks).

218
docs/writing-docs/mdx.md Normal file
View File

@ -0,0 +1,218 @@
---
title:'MDX'
---
MDX is a standard file format that combines Markdown with JSX. This means you can use Markdown’s terse syntax (such as # heading) for your documentation, write stories that compile to our component story format, and freely embed JSX component blocks at any point in the file. All at once.
In addition, you can write pure documentation pages in MDX and add them to Storybook alongside your stories.
### Basic example
Let's get started with an example that combines Markdown with a single story:
```js
// Checkbox.stories.mdx
import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
import { Checkbox } from './Checkbox';
<Meta title="MDX/Checkbox" component={Checkbox} />
# Checkbox
With `MDX` we can define a story for `Checkbox` right in the middle of our
markdown documentation.
export const Template = (args) => <Checkbox {...args} />
<Preview>
<Story name="Unchecked" args={{
label: 'Unchecked'
}}>
{Template.bind({})}
</Story>
<Story name="Checked" args={{
label: 'Unchecked',
checked: true
}}>
{Template.bind({})}
</Story>
<Story name="Secondary" args={{
label: 'Secondary',
checked: true,
appearance: 'secondary'
}}>
{Template.bind({})}
</Story>
</Preview>
```
<div style="background-color:#F8FAFC">
TODO: add image per screenshot requirements (image of basic example of checkbox with mdx)
</div>
As you can see there's a lot going on here. We're writing Markdown, we're writing JSX, and we're also defining Storybook stories that are drop-in compatible with the entire Storybook ecosystem.
Let's break it down.
### MDX-Flavored CSF
MDX-flavored Component Story Format (CSF) includes a collection of components called ["Doc Blocks"](./docs-blocks), that allow Storybook to translate MDX files into Storybook stories. MDX-defined stories are identical to regular Storybook stories, so they can be used with Storybook's entire ecosystem of addons and view layers.
For example, here's the first story from the Checkbox example above, rewritten in CSF:
```js
// Checkbox.stories.js
import React from 'react';
import { Checkbox } from './Checkbox';
export default {
title: "MDX/Checkbox",
component: Checkbox
};
const Template = (args) => <Checkbox {...args} />
export const Unchecked = Template.bind({});
Unchecked.args = { label: 'Unchecked' };
```
There's a one-to-one mapping from the code in MDX to CSF. As a user, this means your existing Storybook knowledge should translate between the two.
### Writing stories
Let's look at a more realistic example to see how MDX works:
```js
// Badge.stories.mdx
import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
import { Badge } from './Badge';
import { Icon } from './Icon';
<Meta title="MDX/Badge" component={Badge} />
export const Template = (args) => <Badge {...args } />
# Badge
Let's define a story for our `Badge` component:
<Story name="positive" args={{
status: 'positive',
label: 'Positive'
}}>
{Template.bind({})}
</Story>
We can drop it in a `Preview` to get a code snippet:
<Preview>
<Story name="negative" args={{
status: 'negative',
label: 'Negative'
}}>
{Template.bind({})}
</Story>
</Preview>
We can even preview multiple Stories in a block. This
gets rendered as a group, but defines individual stories
with unique URLs which is great for review and testing.
<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>
<Story name="with icon" args={{
status: warning,
label: (<Icon icon="check" inline /> with icon)
)}}>
{Template.bind({})}
</Story>
</Story>
</Preview>
```
And here's how that gets rendered in Storybook:
<div style="background-color:#F8FAFC">
TODO: add image per screenshot requirements (image to match the code showed (usage of the badge component))
</div>
### Embedding stories
Suppose you have an existing story and want to embed it into your docs. Here's how to show a story with ID some--id. Check the browser URL in Storybook v5+ to find a story's ID.
```js
import { Story } from "@storybook/addon-docs/blocks";
# Some header
And markdown here
<Story id="some--id" />
```
You can also use the rest of the MDX features in conjunction with embedding. That includes source, preview, and prop tables.
### Decorators and parameters
To add decorators and parameters in MDX:
```js
<Meta
title='MyComponent'
decorators={[ ... ]}
parameters={{ ... }}
/>
<Story name="story" decorators={[ ... ]} parameters={{ ... }} >
...
</Story>
```
Global parameters and decorators work just like before.
### Documentation-only MDX
Typically, when you use Storybook MDX, you define stories in the MDX and documentation is automatically associated with those stories. But what if you want to write Markdown-style documentation without any stories inside?
If you don't define stories in your MDX, you can write MDX documentation and associate it with an existing story, or embed that MDX as its own documentation node in your Storybook's navigation.
<div style="background-color:#F8FAFC">
TODO: ask tom about the "CSF Stories with MDX Docs" link if that's where it should be pointing
</div>
If you don't define a Meta, you can write Markdown and associate with an existing story. See ["CSF Stories with MDX Docs"](https://github.com/storybookjs/storybook/blob/master/addons/docs/docs/recipes.md#csf-stories-with-mdx-docs).
To get a "documentation-only story", in your UI, define a `<Meta>` as you normally would, but don't define any stories. It will show up in your UI as a documentation node:
<div style="background-color:#F8FAFC">
TODO:add image per screenshot requirements (Screenshot to match documentation (check if the mdx shown is the default one for Storybook 6))
</div>
### MDX file names
Unless you use a custom [webpack configuration](../configure/integration#extending-storybooks-webpack-config), all of your MDX files should have the suffix `*.stories.mdx`. This tells Storybook to apply its special processing to the `<Meta>` and `<Story>` elements in the file.
> Be sure to update [.storybook/main.js](../configure/overview#configure-story-rendering) file to load `.stories.mdx` stories, as per the addon-docs installation instructions.