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

Adds Docs 2 documentation

Browse Source
This commit is contained in:
jonniebigodes 2022-12-13 18:22:21 +00:00
parent 8063a0ed6f
commit df17553de0
30 changed files with 633 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/faq.md
View File

@ -4,36 +4,35 @@ title: 'Frequently Asked Questions'
Here are some answers to frequently asked questions. If you have a question, you can ask it by opening an issue on the [Storybook Repository](https://github.com/storybookjs/storybook/).
* [How can I opt-out of Angular Ivy?](#how-can-i-opt-out-of-angular-ivy)
* [How can I opt-out of Angular ngcc?](#how-can-i-opt-out-of-angular-ngcc)
* [How can I run coverage tests with Create React App and leave out stories?](#how-can-i-run-coverage-tests-with-create-react-app-and-leave-out-stories)
* [I see `ReferenceError: React is not defined` when using Storybook with Next.js](#i-see-referenceerror-react-is-not-defined-when-using-storybook-with-nextjs)
* [How do I setup Storybook to share Webpack configuration with Next.js?](#how-do-i-setup-storybook-to-share-webpack-configuration-with-nextjs)
* [How do I setup React Fast Refresh with Storybook?](#how-do-i-setup-react-fast-refresh-with-storybook)
* [How do I setup the new React Context Root API with Storybook?](#how-do-i-setup-the-new-react-context-root-api-with-storybook)
* [Why is there no addons channel?](#why-is-there-no-addons-channel)
* [Why aren't Controls visible in the Canvas panel but visible in the Docs panel?](#why-arent-controls-visible-in-the-canvas-panel-but-visible-in-the-docs-panel)
* [Why aren't the addons working in a composed Storybook?](#why-arent-the-addons-working-in-a-composed-storybook)
* [Which community addons are compatible with the latest version of Storybook?](#which-community-addons-are-compatible-with-the-latest-version-of-storybook)
* [Is it possible to browse the documentation for past versions of Storybook?](#is-it-possible-to-browse-the-documentation-for-past-versions-of-storybook)
* [What icons are available for my toolbar or my addon?](#what-icons-are-available-for-my-toolbar-or-my-addon)
* [I see a "No Preview" error with a Storybook production build](#i-see-a-no-preview-error-with-a-storybook-production-build)
* [Can I use Storybook with Vue 3?](#can-i-use-storybook-with-vue-3)
* [Is snapshot testing with Storyshots supported for Vue 3?](#is-snapshot-testing-with-storyshots-supported-for-vue-3)
* [Why are my MDX stories not working in IE11?](#why-are-my-mdx-stories-not-working-in-ie11)
* [Why aren't my code blocks highlighted with Storybook MDX](#why-arent-my-code-blocks-highlighted-with-storybook-mdx)
* [Why aren't my MDX 2 stories working in Storybook?](#why-arent-my-mdx-2-stories-working-in-storybook)
* [Why can't I import my own stories into MDX 2?](#why-cant-i-import-my-own-stories-into-mdx-2)
* [Why are my mocked GraphQL queries failing with Storybook's MSW addon?](#why-are-my-mocked-graphql-queries-failing-with-storybooks-msw-addon)
* [Can I use other GraphQL providers with Storybook's MSW addon?](#can-i-use-other-graphql-providers-with-storybooks-msw-addon)
* [Can I mock GraphQL mutations with Storybook's MSW addon?](#can-i-mock-graphql-mutations-with-storybooks-msw-addon)
* [How can my code detect if it is running in Storybook?](#how-can-my-code-detect-if-it-is-running-in-storybook)
* [Why are my stories not showing up correctly when using certain characters?](#why-are-my-stories-not-showing-up-correctly-when-using-certain-characters)
* [Why are the TypeScript examples and documentation using `as` for type safety?](#why-are-the-typescript-examples-and-documentation-using-as-for-type-safety)
* [Why is Storybook's source loader returning undefined with curried functions?](#why-is-storybooks-source-loader-returning-undefined-with-curried-functions)
* [Why are my args no longer displaying the default values?](#why-are-my-args-no-longer-displaying-the-default-values)
* [Why isn't Storybook's test runner working?](#why-isnt-storybooks-test-runner-working)
* [How does Storybook handle environment variables?](#how-does-storybook-handle-environment-variables)
- [How can I opt-out of Angular Ivy?](#how-can-i-opt-out-of-angular-ivy)
- [How can I opt-out of Angular ngcc?](#how-can-i-opt-out-of-angular-ngcc)
- [How can I run coverage tests with Create React App and leave out stories?](#how-can-i-run-coverage-tests-with-create-react-app-and-leave-out-stories)
- [I see `ReferenceError: React is not defined` when using Storybook with Next.js](#i-see-referenceerror-react-is-not-defined-when-using-storybook-with-nextjs)
- [How do I setup Storybook to share Webpack configuration with Next.js?](#how-do-i-setup-storybook-to-share-webpack-configuration-with-nextjs)
- [How do I setup React Fast Refresh with Storybook?](#how-do-i-setup-react-fast-refresh-with-storybook)
- [How do I setup the new React Context Root API with Storybook?](#how-do-i-setup-the-new-react-context-root-api-with-storybook)
- [Why is there no addons channel?](#why-is-there-no-addons-channel)
- [Why aren't Controls visible in the Canvas panel but visible in Docs?](#why-arent-controls-visible-in-the-canvas-panel-but-visible-in-docs)
- [Why aren't the addons working in a composed Storybook?](#why-arent-the-addons-working-in-a-composed-storybook)
- [Which community addons are compatible with the latest version of Storybook?](#which-community-addons-are-compatible-with-the-latest-version-of-storybook)
- [Is it possible to browse the documentation for past versions of Storybook?](#is-it-possible-to-browse-the-documentation-for-past-versions-of-storybook)
- [What icons are available for my toolbar or my addon?](#what-icons-are-available-for-my-toolbar-or-my-addon)
- [I see a "No Preview" error with a Storybook production build](#i-see-a-no-preview-error-with-a-storybook-production-build)
- [Can I use Storybook with Vue 3?](#can-i-use-storybook-with-vue-3)
- [Is snapshot testing with Storyshots supported for Vue 3?](#is-snapshot-testing-with-storyshots-supported-for-vue-3)
- [Why aren't my code blocks highlighted with Storybook MDX](#why-arent-my-code-blocks-highlighted-with-storybook-mdx)
- [Why aren't my MDX 2 stories working in Storybook?](#why-arent-my-mdx-2-stories-working-in-storybook)
- [Why can't I import my own stories into MDX 2?](#why-cant-i-import-my-own-stories-into-mdx-2)
- [Why are my mocked GraphQL queries failing with Storybook's MSW addon?](#why-are-my-mocked-graphql-queries-failing-with-storybooks-msw-addon)
- [Can I use other GraphQL providers with Storybook's MSW addon?](#can-i-use-other-graphql-providers-with-storybooks-msw-addon)
- [Can I mock GraphQL mutations with Storybook's MSW addon?](#can-i-mock-graphql-mutations-with-storybooks-msw-addon)
- [How can my code detect if it is running in Storybook?](#how-can-my-code-detect-if-it-is-running-in-storybook)
- [Why are my stories not showing up correctly when using certain characters?](#why-are-my-stories-not-showing-up-correctly-when-using-certain-characters)
- [Why are the TypeScript examples and documentation using `as` for type safety?](#why-are-the-typescript-examples-and-documentation-using-as-for-type-safety)
- [Why is Storybook's source loader returning undefined with curried functions?](#why-is-storybooks-source-loader-returning-undefined-with-curried-functions)
- [Why are my args no longer displaying the default values?](#why-are-my-args-no-longer-displaying-the-default-values)
- [Why isn't Storybook's test runner working?](#why-isnt-storybooks-test-runner-working)
- [How does Storybook handle environment variables?](#how-does-storybook-handle-environment-variables)
### How can I opt-out of Angular Ivy?
@ -55,6 +54,7 @@ module.exports = {
},
};
```
### How can I opt-out of Angular ngcc?
In case you postinstall ngcc, you can disable it:
@ -171,7 +171,7 @@ A common error is that an addon tries to access the "channel", but the channel i
2. In React Native, it's a special case documented in [#1192](https://github.com/storybookjs/storybook/issues/1192)
### Why aren't Controls visible in the Canvas panel but visible in the Docs panel?
### Why aren't Controls visible in the Canvas panel but visible in Docs?
If you're adding Storybook's dependencies manually, make sure you include the [`@storybook/addon-controls`](https://www.npmjs.com/package/@storybook/addon-controls) dependency in your project and reference it in your `.storybook/main.js` as follows:
@ -218,7 +218,7 @@ We're only covering versions 5.3 and 5.0 as they were important milestones for S
| | Naming components and hierarchy | [See current documentation](./writing-stories/naming-components-and-hierarchy.md) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/basics/writing-stories) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/basics/writing-stories) |
| | Build pages and screens | [See current documentation](./writing-stories/build-pages-with-storybook.md) | Non existing feature or undocumented | Non existing feature or undocumented |
| | Stories for multiple components | [See current documentation](./writing-stories/stories-for-multiple-components.md) | Non existing feature or undocumented | Non existing feature or undocumented |
| Write docs | DocsPage | [See current documentation](./writing-docs/docs-page.md) | See versioned addon documentation | Non existing feature or undocumented |
| Write docs | Docs | [See current documentation](./writing-docs/docs-page.md) | See versioned addon documentation | Non existing feature or undocumented |
| | MDX | [See current documentation](./writing-docs/mdx.md) | See versioned addon documentation | Non existing feature or undocumented |
| | Doc Blocks/Argstable | [See current documentation](./writing-docs/doc-block-argstable.md) | [See versioned addon documentation](https://github.com/storybookjs/storybook/tree/release/5.3/addons/docs/) | Non existing feature or undocumented |
| | Doc Blocks/Canvas | [See current documentation](./writing-docs/doc-block-canvas.md) | [See versioned addon documentation](https://github.com/storybookjs/storybook/tree/release/5.3/addons/docs/) | Non existing feature or undocumented |
@ -308,10 +308,6 @@ If you run into a situation where this is not the case, you can adjust the `conf
See our documentation on how to customize the [Storyshots configuration](./writing-tests/snapshot-testing.md).
### Why are my MDX stories not working in IE11?
Currently there's an issue when using MDX stories with IE11. This issue does <strong>not</strong> apply to [DocsPage](./writing-docs/docs-page.md). If you're interested in helping us fix this issue, read our <a href="https://github.com/storybookjs/storybook/blob/next/CONTRIBUTING.md">Contribution guidelines</a> and submit a pull request.
### Why aren't my code blocks highlighted with Storybook MDX
Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) that you can use with your code blocks. If you're writing your custom code blocks with MDX, you'll need to import the syntax highlighter manually. For example, if you're adding a code block for SCSS, adjust your story to the following:

34
docs/snippets/angular/button-story-auto-docs.ts.mdx Normal file
View File

@ -0,0 +1,34 @@
```ts
// Button.stories.ts
import type { Meta, StoryObj } from '@storybook/angular';
import { Button } from './button.component';
const meta: Meta<Button> = {
title: 'Button',
component: Button,
//👇 Enables auto-generated documentation for the component story
tags: ['docsPage'],
argTypes: {
backgroundColor: { control: 'color' },
},
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
primary: true,
label: 'Button',
},
};
export const Secondary: Story = {
args: {
...Primary.args,
primary: false,
},
};
```

30
docs/snippets/common/storybook-auto-docs-baseline-example.mdx.mdx Normal file
View File

@ -0,0 +1,30 @@
```mdx
{/* Button.mdx */}
import { Meta } from '@storybook/blocks';
<Meta title="Button" />
# Definition
Button is a clickable interactive element that triggers a response.
You can place text and icons inside of a button.
Buttons are often used for form submissions and to toggle elements into view.
## Usage
The component comes in different variants such as `primary`, `secondary`, `large` and `small` which you can use to alter the look and feel of the button.
## Inputs
Button has the following properties:
- `primary` - If `true`, the button will have a primary style.
- `size` - The size of the button.
- `label` - The label of the button.
- `backgroundColor` - The background color of the button.
- `onClick` - Callback function when clicked.
```

22
docs/snippets/common/storybook-auto-docs-full-config.js.mdx Normal file
View File

@ -0,0 +1,22 @@
```js
// .storybook/main.js
module.exports = {
stories: ['../src/**/*.stories.@(js|ts)'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-interactions',
],
framework: {
// Replace your-framework with the name of your framework (e.g., react-webpack5, vue3-webpack5)
name: '@storybook/your-framework',
options: {},
},
docs: {
enabled: false,
docsPage: false,
defaultName: 'Documentation',
},
};
```

27
docs/snippets/common/storybook-auto-docs-full-config.ts.mdx Normal file
View File

@ -0,0 +1,27 @@
```ts
// .storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-webpack5)
import type { StorybookConfig } from '@storybook/your-framework';
const config: StorybookConfig = {
stories: ['../src/**/*.stories.@(js|ts)'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-interactions',
],
framework: {
// The name of the framework you want to use goes here
name: '@storybook/your-framework',
options: {},
},
docs: {
enabled: false,
docsPage: false,
defaultName: 'Documentation',
},
};
export default config;
```

17
docs/snippets/common/storybook-auto-docs-main-mdx-config.js.mdx Normal file
View File

@ -0,0 +1,17 @@
```js
// .storybook/main.js
module.exports = {
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|ts)'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-interactions',
],
framework: {
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-webpack5)
name: '@storybook/your-framework',
options: {},
},
};
```

22
docs/snippets/common/storybook-auto-docs-main-mdx-config.ts.mdx Normal file
View File

@ -0,0 +1,22 @@
```ts
// .storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-webpack5)
import type { StorybookConfig } from '@storybook/your-framework';
const config: StorybookConfig = {
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|ts)'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-interactions',
],
framework: {
// The name of the framework you want to use goes here
name: '@storybook/your-framework',
options: {},
},
};
export default config;
```

34
docs/snippets/common/storybook-auto-docs-mdx-file.mdx.mdx Normal file
View File

@ -0,0 +1,34 @@
```mdx
{/* Page.mdx */}
import { Canvas, Meta, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
import * as PageStories from './Page.stories';
<Meta of={ButtonStories} />
# Definition
Button is a clickable interactive element that triggers a response.
You can place text and icons inside of a button.
Buttons are often used for form submissions and to toggle elements into view.
## Usage
<Canvas withToolbar>
<Story of={ButtonStories.Basic} />
</Canvas>
## Definition
Page is a layout container that is used to position children in predetermined areas.
It's often used to apply consistent positioning for content across pages in an application.
## Usage
<Story of={PageStories.Basic} meta={PageStories} />
```

20
docs/snippets/common/storybook-auto-docs-override-mdx-container.js.mdx Normal file
View File

@ -0,0 +1,20 @@
```js
// CustomPageProvider.js
import { MDXProvider } from '@mdx-js/react';
import { DocsContainer } from '@storybook/blocks';
import * as DesignSystem from 'your-design-system';
export const MyDocsContainer = (props) => (
<MDXProvider
components={{
h1: DesignSystem.H1,
h2: DesignSystem.H2,
}}
>
<DocsContainer {...props} />
</MDXProvider>
);
```

21
docs/snippets/common/storybook-auto-docs-starter-example.mdx.mdx Normal file
View File

@ -0,0 +1,21 @@
```mdx
{/* Button.mdx */}
import { Meta, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
<Meta of={ButtonStories} />
# Definition
Button is a clickable interactive element that triggers a response.
You can place text and icons inside of a button.
Buttons are often used for form submissions and to toggle elements into view.
## Usage
<Story of={ButtonStories.Basic} />
```

31
docs/snippets/common/storybook-preview-auto-docs-custom-docs-container.js.mdx Normal file
View File

@ -0,0 +1,31 @@
```js
// .storybook/preview.js
import { DocsContainer } from '@storybook/blocks';
const ExampleContainer = (props) => {
const { children } = props;
return (
<DocsContainer {...props}>
<div>
<h1>Starter documentation</h1>
<h2>Storybook's auto-generated documentation page uses this custom container.</h2>
<div>{children}</div>
</div>
</DocsContainer>
);
};
export const parameters = {
actions: { argTypesRegex: '^on[A-Z].*' },
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/,
},
},
docs: {
container: (props) => <ExampleContainer {...props} />,
},
};
```

18
docs/snippets/common/storybook-preview-auto-docs-custom-template.js.mdx Normal file
View File

@ -0,0 +1,18 @@
```js
// .storybook/preview.js
import DocumentationTemplate from './DocumentationTemplate.mdx';
export const parameters = {
actions: { argTypesRegex: '^on[A-Z].*' },
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/,
},
},
docs: {
page: DocumentationTemplate, // The replacement template to use
},
};
```

18
docs/snippets/common/storybook-preview-auto-docs-override-theme.js.mdx Normal file
View File

@ -0,0 +1,18 @@
```js
// .storybook/preview.js
import { themes, ensure } from '@storybook/theming';
export const parameters = {
actions: { argTypesRegex: '^on[A-Z].*' },
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/,
},
},
docs: {
theme: ensure(themes.dark), // The replacement theme to use
},
};
```

15
docs/snippets/common/storybook-preview-auto-docs-template.mdx.mdx Normal file
View File

@ -0,0 +1,15 @@
```mdx
{/* CustomTemplate.mdx */}
# Get started
This is an overview of the steps you need to take to get started with the UI component.
## Set up your environment
You need to set up your environment to run the examples. You can do this by following the instructions in the Getting Started guide.
## Run the examples
You can run the examples by following the instructions in the Running the examples guide.
```

29
docs/snippets/react/button-story-auto-docs.js.mdx Normal file
View File

@ -0,0 +1,29 @@
```js
// Button.stories.js
import { Button } from './Button';
export default {
title: 'Button',
component: Button,
//👇 Enables auto-generated documentation for the component story
tags: ['docsPage'],
argTypes: {
backgroundColor: { control: 'color' },
},
};
export const Primary = {
args: {
primary: true,
label: 'Button',
},
};
export const Secondary = {
args: {
...Primary.args,
primary: false,
},
};
```

34
docs/snippets/react/button-story-auto-docs.ts.mdx Normal file
View File

@ -0,0 +1,34 @@
```tsx
// Button.stories.ts
import type { Meta } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
title: 'Button',
component: Button,
//👇 Enables auto-generated documentation for the component story
tags: ['docsPage'],
argTypes: {
backgroundColor: { control: 'color' },
},
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
primary: true,
label: 'Button',
},
};
export const Secondary: Story = {
args: {
...Primary.args,
primary: false,
},
};
```

42
docs/snippets/svelte/button-story-auto-docs.js.mdx Normal file
View File

@ -0,0 +1,42 @@
```js
// Button.stories.js
import Button from './Button.svelte';
export default {
title: 'Button',
component: Button,
//👇 Enables auto-generated documentation for the component story
tags: ['docsPage'],
argTypes: {
backgroundColor: { control: 'color' },
},
};
/*
*👇 Render functions are a framework specific feature to allow you control on how the component renders.
* See https://storybook.js.org/docs/7.0/svelte/api/csf
* to learn how to use render functions.
*/
export const Primary = {
render: (args) => ({
Component: Button,
props: args,
}),
args: {
primary: true,
label: 'Button',
},
};
export const Secondary = {
render: (args) => ({
Component: Button,
props: args,
}),
args: {
...Primary.args,
primary: false,
},
};
```

29
docs/snippets/vue/button-story-auto-docs.js.mdx Normal file
View File

@ -0,0 +1,29 @@
```js
// Button.stories.js
import Button from './Button.vue';
export default {
title: 'Button',
component: Button,
//👇 Enables auto-generated documentation for the component story
tags: ['docsPage'],
argTypes: {
backgroundColor: { control: 'color' },
},
};
export const Primary = {
args: {
primary: true,
label: 'Button',
},
};
export const Secondary = {
args: {
...Primary.args,
primary: false,
},
};
```

35
docs/snippets/vue/button-story-auto-docs.ts.mdx Normal file
View File

@ -0,0 +1,35 @@
```ts
// Button.stories.ts
import Button from './Button.vue';
// Replace vue3 with vue if you are using Storybook for Vue 2
import type { Meta, StoryObj } from '@storybook/vue3';
const meta: Meta<typeof Button> = {
title: 'Button',
component: Button,
//👇 Enables auto-generated documentation for the component story
tags: ['docsPage'],
argTypes: {
backgroundColor: { control: 'color' },
},
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
primary: true,
label: 'Button',
},
};
export const Secondary: Story = {
args: {
...Primary.args,
primary: false,
},
};
```

2
docs/toc.js
View File

@ -112,7 +112,7 @@ module.exports = {
},
{
pathSegment: 'docs-page',
title: 'DocsPage',
title: 'Docs',
type: 'link',
},
{

BIN
docs/writing-docs/addon-docs-optimized.mp4
View File

Binary file not shown.

6
docs/writing-docs/build-documentation.md
View File

@ -53,3 +53,9 @@ You can use any hosting provider to deploy your documentation, for instance:
- [Vercel](https://vercel.com/)
- [Netlify](https://www.netlify.com/)
- [S3](https://aws.amazon.com/en/s3/)
#### Learn more about Storybook documentation
- [Docs](./docs-page.md) for creating documentation for your stories
- [MDX](./mdx.md) for customizing your documentation
- Publishing docs to automate the process of publishing your documentation

4
docs/writing-docs/doc-block-argstable.md
View File

@ -30,9 +30,9 @@ This is extremely useful, but it can be further expanded. Additional information
The args tables will be updated accordingly by including the additional information (e.g., JSDocs comments), offering a richer experience for any stakeholders involved.
## Working with the DocsPage
## Working with Docs
To use the `ArgsTable` in [DocsPage](./docs-page.md#component-parameter), export a component property on your stories metadata:
To use the `ArgsTable` in Storybook's Docs, export a component property on your stories metadata:
<!-- prettier-ignore-start -->

4
docs/writing-docs/doc-block-canvas.md
View File

@ -6,9 +6,9 @@ Storybook's `Canvas` Doc Block is a wrapper featuring a toolbar that allows you
![Docs block with a story preview](./docblock-preview.png)
## Working with the DocsPage
## Working with Docs
Storybook's [DocsPage](./docs-page.md) wraps each story inside a `Canvas` Doc Block. The first story rendered in the DocsPage is automatically configured with a toolbar and set as _primary_. All other existing stories will not feature the toolbar. It also includes a [Source](./doc-block-source.md) Doc Block to visualize the story code snippet.
Storybook's [Docs](./docs-page.md) wraps each story inside a `Canvas` Doc Block. The first story rendered in the DocsPage is automatically configured with a toolbar and set as _primary_. All other existing stories will not feature the toolbar. It also includes a [Source](./doc-block-source.md) Doc Block to visualize the story code snippet.
## Working with MDX

2
docs/writing-docs/doc-block-source.md
View File

@ -6,7 +6,7 @@ Storybook's `Source` Doc Block displays the story's source code. It supports syn
![Docs blocks with source](./docblock-source.png)
## Working with the DocsPage
## Working with Docs
Storybook automatically generates a `Source` Doc Block within the [Canvas](./doc-block-canvas.md) to display the story's code snippet.
It includes additional customization via parameters. Below is a condensed example and tables featuring all the available options.

47
docs/writing-docs/doc-block-story.md
View File

@ -7,46 +7,29 @@ In Storybook Docs, stories are rendered in the `Story` block.
![Docs blocks with stories](./docblock-story.png)
## Working with the DocsPage
## Working with Docs
With each story you write, Storybook will automatically generate a new `Story` Doc Block, wrapped inside a [`Canvas`](./doc-block-canvas.md)(with a toolbar if it's the first "primary" story) alongside a [source code ](./doc-block-source.md) preview underneath it. Below is a condensed table of the available configuration options.
With each story you write, Storybook will automatically generate a new `Story` Doc Block, wrapped inside a [`Canvas`](./doc-block-canvas.md)(with a toolbar if it's the first "primary" story) alongside a [source code](./doc-block-source.md) preview underneath it. Below is a condensed table of the available configuration options.
| Option | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inlineStories` | Configures Storybook to render stories inline. <br/> `docs: { inlineStories: false }` <br/> Read the [documentation](./docs-page.md#inline-stories-vs-iframe-stories) for inline rendering framework support. |
| Option | Description |
| --------------- | ------------------------------------------------------------------------------------- |
| `inlineStories` | Configures Storybook to render stories inline. <br/> `docs: { inlineStories: false }` |
## Working with MDX
With MDX, the `Story` block is not only a way of rendering stories, but how you define them. Internally, Storybook looks for named `Story` instances located at the top of your document, or inside a [Canvas](./doc-block-canvas.md). Below is an abridged example and table featuring all the available options.
| Option | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `args` | Provide the required component inputs (e.g., props). <br/> `<Story args={{ text: 'Button' }}/>` <br/> Read the [documentation](../writing-stories/args.md) to learn more. |
| Option | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `args` | Provide the required component inputs (e.g., props). <br/> `<Story args={{ text: 'Button' }}/>` <br/> Read the [documentation](../writing-stories/args.md) to learn more. |
| `decorators` | Provide additional markup or mock a data provider to allow proper story rendering. <br/> `<Story decorators={[(Story) => ( <div style={{ margin: '3em' }}><Story/></div>)]}/>` <br/> Read the [documentation](../writing-stories/decorators.md) to learn more. |
| `id` | Storybook's internal story identifier. Used for embedding Storybook stories inside Docs. <br/> `<Story id="example-mycomponent--starter"/>` <br/> Read the [documentation](../api/mdx.md#embedding-stories) to learn more. |
| `inline` | Enables Storybook's inline renderer. <br/> `<Story inline={false}/>` <br/> Read the [documentation](./docs-page.md#inline-stories-vs-iframe-stories) to learn more. |
| `loaders` | (Experimental) Asynchronous function for data fetching with stories. <br/> `<Story loaders={[async () => ({ data: await (await fetch('your-endpoint'))}) ]}/>` <br/> Read the [documentation](../writing-stories/loaders.md) to learn more. |
| `name` | Adds a name to the component story. <br/> `<Story name="Example"/>` . |
| `parameters` | Provides the necessary static named metadata related to the story. <br/> `Story parameters={{ backgrounds: { values: [{ name:'red', value:'#f00' }] } }} />` <br/> Read the [documentation](../writing-stories/parameters.md) to learn more. |
| `play` | Generate component interactions. <br/> `<Story play={async () => { await userEvent.click(screen.getByRole('button')) }}/>` <br/> Read the [documentation](../writing-stories/play-function.md) to learn more. |
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'react/component-story-mdx-story-by-name.mdx.mdx',
'angular/component-story-mdx-story-by-name.mdx.mdx',
'vue/component-story-mdx-story-by-name.mdx-2.mdx.mdx',
'vue/component-story-mdx-story-by-name.mdx-3.mdx.mdx',
'svelte/component-story-mdx-story-by-name.mdx.mdx',
'common/component-story-mdx-reference-storyid.mdx.mdx',
]}
usesCsf3
csf2Path="writing-docs/doc-block-story#snippet-component-story-mdx-story-by-name"
/>
<!-- prettier-ignore-end -->
| `id` | Storybook's internal story identifier. Used for embedding Storybook stories inside Docs. <br/> `<Story id="example-mycomponent--starter"/>` <br/> Read the [documentation](../api/mdx.md#embedding-stories) to learn more. |
| `inline` | Enables Storybook's inline renderer. <br/> `<Story inline={false}/>` |
| `loaders` | (Experimental) Asynchronous function for data fetching with stories. <br/> `<Story loaders={[async () => ({ data: await (await fetch('your-endpoint'))}) ]}/>` <br/> Read the [documentation](../writing-stories/loaders.md) to learn more. |
| `name` | Adds a name to the component story. <br/> `<Story name="Example"/>` . |
| `parameters` | Provides the necessary static named metadata related to the story. <br/> `Story parameters={{ backgrounds: { values: [{ name:'red', value:'#f00' }] } }} />` <br/> Read the [documentation](../writing-stories/parameters.md) to learn more. |
| `play` | Generate component interactions. <br/> `<Story play={async () => { await userEvent.click(screen.getByRole('button')) }}/>` <br/> Read the [documentation](../writing-stories/play-function.md) to learn more. |
### Inline rendering
All stories are rendered in the Preview iframe for isolated development in Storybook's Canvas. With Docs, if your framework supports [inline rendering](./docs-page.md#inline-stories-vs-iframe-stories), it will be used by default for both performance and convenience. However, you can force this feature by providing the required configuration option (see tables above).
All stories are rendered in the Preview iframe for isolated development in Storybook's Canvas. With Docs, if your framework supports inline rendering, it will be used by default for both performance and convenience. However, you can force this feature by providing the required configuration option (see tables above).

199
docs/writing-docs/docs-page.md
View File

@ -1,205 +1,188 @@
---
title: 'DocsPage'
title: 'Docs'
---
When you install [Storybook Docs](https://storybook.js.org/addons/@storybook/addon-docs), DocsPage is the zero-config default documentation that all stories get out of the box. It aggregates your [stories](../get-started/whats-a-story.md), text descriptions, docgen comments, [args tables](./doc-block-argstable.md), and code examples into a single page for each component.
Documentation is an essential part of modern UI development, as it serves as a reference for developers who may need to understand or integrate your components into their own projects. Well-written documentation can help to promote the project and make it more accessible to a broader audience. Overall, the importance of writing documentation cannot be overstated, as it is a key factor in the success of any project.
The best practice for docs is for each component to have its own set of documentation and stories.
In Storybook, this workflow happens automatically. When you write stories for your components, you create living, interactive, sustainable documentation.
## Component parameter
## How does documentation work in Storybook?
Storybook uses the `component` key in the story file’s default export to extract the component's description and props.
You start by writing a [**story**](../writing-stories/introduction) for your component to define the different states it can be in. Then generate the baseline **documentation** for your story via `tags`. Finally, customize the documentation with [MDX](./mdx.md) and Storybook's **Doc Blocks** to fully control how the content gets rendered.
## Setup automated documentation
To enable auto-generated documentation for your stories, you'll need to add the `tags` configuration property to the story's default export. For example:
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/my-component-story.js.mdx',
'react/button-story-auto-docs.js.mdx',
'react/button-story-auto-docs.ts.mdx',
'vue/button-story-auto-docs.js.mdx',
'vue/button-story-auto-docs.ts.mdx',
'angular/button-story-auto-docs.ts.mdx',
'svelte/button-story-auto-docs.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
## Subcomponents parameter
<video autoPlay muted playsInline loop>
<source
src="storybook-button-auto-docs-optimized.mp4"
type="video/mp4"
/>
</video>
Sometimes it's helpful to document multiple components together. For example, a component library’s ButtonGroup and Button components might not make sense without one another.
Once the story loads, Storybook infers the relevant metadata (e.g., [`args`](../writing-stories/args.md), [`argTypes`](../api/argtypes.md), [`parameters`](../writing-stories/parameters.md)) and automatically generates a documentation page with this information positioned at the root-level.
DocsPage has the concept of a "primary" component defined by the `component` parameter. It also accepts one or more `subcomponents`.
### Configure
By default, Storybook offers zero-config support for documentation and automatically sets up a documentation page for each story enabled via the `tags` configuration property. However, you can extend your Storybook configuration file (i.e., `.storybook/main.js|ts|cjs`) and provide additional options to control how documentation gets created. Listed below are the available options and examples of how to use them.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/button-group-story-subcomponents.js.mdx',
'common/button-group-story-subcomponents.ts.mdx'
'common/storybook-auto-docs-full-config.js.mdx',
'common/storybook-auto-docs-full-config.ts.mdx',
]}
/>
<!-- prettier-ignore-end -->
![Subcomponents in Docs Page](./docspage-subcomponents.png)
| Option | Description |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `enabled` | Disables auto-generated documentation pages<br/> `docs: { enabled:false }` |
| `docsPage` | Disables auto-generated documentation pages created via `tags` <br/> `docs: { docsPages: false }` |
| `defaultName` | Renames the auto-generated documentation page<br/> `docs: { defaultName: 'Documentation' }` |
Subcomponent `ArgsTables` will show up in a tabbed interface along with the primary component. The tab titles will correspond to the keys of the subcomponents object.
### Write a custom template
If you want to organize your documentation differently for component groups, we recommend using MDX. It gives you complete control over how it's displayed and supports any configuration.
## Replacing DocsPage
Replace the DocsPage template with your own to customize its contents.
### With null to remove docs
Override the `docs.page` [parameter](../writing-stories/parameters.md) with `null` to remove its contents.
To replace the default documentation templated used by Storybook, you can create your own template written in MDX and update your UI configuration file (i.e., `.storybook/preview.js`) to point to it.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/button-story-disable-docspage-component.js.mdx',
'common/storybook-preview-auto-docs-custom-template.js.mdx',
'common/storybook-preview-auto-docs-template.mdx.mdx',
]}
/>
<!-- prettier-ignore-end -->
### With MDX documentation
<div class="aside">
Write your documentation in MDX and update the `docs.page` [parameter](../writing-stories/parameters.md) to display it. The `id` of reference follows the pattern: `group-subgroup-...--name`, where the `groups` and `subgroups` are defined as according to the [Grouping Documentation](https://storybook.js.org/docs/react/writing-stories/naming-components-and-hierarchy#grouping).
💡 If you only need to override the documentation page for a single component, we recommend creating an MDX file and referencing it directly via the `<Meta of={} />` Doc Block.
</div>
## Setup custom documentation
Storybook provides support for MDX 2, an open standard markup language, combining two other ones: Markdown, which is used for formatting text, and JSX, which is used for rendering dynamic elements on a page. To enable custom documentation for your stories with this format, start by updating your Storybook configuration file (i.e., `.storybook/main.js|ts|cjs`).
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/custom-docs-page.mdx.mdx',
'common/button-story-docspage-with-mdx.js.mdx',
'common/storybook-auto-docs-main-mdx-config.js.mdx',
'common/storybook-auto-docs-main-mdx-config.ts.mdx',
]}
/>
<!-- prettier-ignore-end -->
### With a custom component
Storybook's UI is built using React. If you want to include a custom component to display documentation, you'll need to update your environment to allow React components to be correctly transpiled.
For example, with Angular start by adding a `babel.config.js` file at the root of the project with the following content:
```js
// babel.config.js
module.exports = function (api) {
process.env.NODE_ENV === 'development' ? api.cache(false) : api.cache(true);
const presets = [
[
'@babel/preset-env',
{
targets: {
node: 'current',
},
},
],
'@babel/preset-typescript',
'@babel/preset-react',
];
const plugins = [];
return {
presets,
plugins,
};
};
```
Then, update your `tsconfig.json` to include the following:
```json
{
"compilerOptions": {
....
"allowJs": true,
"jsx": "react-jsx",
},
}
```
Finally write your custom React component and update the `docs.page` [parameter](../writing-stories/parameters.md) to render the custom documentation.
Create an MDX file for your component in the same directory as your stories and components to add your custom documentation. The file should match your component's name (e.g., `Button.mdx`).
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/custom-docs-page.js-component.js.mdx',
'common/custom-docs-page.ts-component.ts.mdx',
'common/button-story-docspage-with-custom-component.js.mdx',
'common/storybook-auto-docs-baseline-example.mdx.mdx',
]}
/>
<!-- prettier-ignore-end -->
## Remixing DocsPage using doc blocks
Once the MDX documentation is loaded, Storybook will render it alongside your component's story overriding any existing documentation enabled via the [`tags`](#setup-automated-docs) configuration property.
Doc blocks are the basic building blocks of Storybook Docs. DocsPage composes them to provide a reasonable UI documentation experience out of the box.
### Fully control custom documentation
If you want to make minor customizations to the default DocsPage but don’t want to write your 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:
Documentation can be expensive to maintain and keep up to date when applied to every project component. To help simplify this process, Storybook provides a set of useful UI components (i.e., Doc Blocks) to help cover more advanced cases. If you need additional content, use them to help create your custom documentation.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/button-story-remix-docspage.js.mdx',
'common/button-story-remix-docspage.ts.mdx',
'common/storybook-auto-docs-starter-example.mdx.mdx',
]}
/>
<!-- prettier-ignore-end -->
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.
### Working with multiple components
## Story file names
Unless you use a custom [Webpack configuration](../builders/webpack.md#extending-storybooks-webpack-config), all of your story files should have the suffix `*.stories.@(j|t)sx?`. For example, "Badge.stories.js" or "Badge.stories.tsx". 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 on one page. You have the option of rendering those stories inline or in an iframe.
The iframe creates a clean separation between your code and Storybook’s UI, which is useful if your stories are rendering correctly in the Canvas but not on the docs page, for instance with fixed positioned components like modals.
But using an iframe has disadvantages. For example, you have to set the height of iframe stories explicitly, or you’ll see a scroll bar. Having more than a few iframe stories on a page can lead to performance issues. And certain dev tools might not work right.
Therefore, we recommend inline rendering where possible. It's the default mode for all the frameworks in which [we support it](../api/frameworks-feature-support.md). The one exception is Angular, where it's opt-in.
To toggle the between the two settings, set `docs.inlineStories` in `.storybook/preview.js`. Like most [parameters](../writing-stories/parameters.md), you can also toggle at the component or story level:
If you need to document multiple components in a single documentation page, you can reference them directly inside your MDX file. Internally, Storybook looks for the story metadata and composes it alongside your existing documentation. For example:
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-preview-optout-inline.js.mdx',
'common/storybook-auto-docs-mdx-file.mdx.mdx',
]}
/>
<!-- prettier-ignore-end -->
### Custom inline rendering
## Advanced configuration
If your framework doesn't [support inline rendering](../api/frameworks-feature-support.md), you also need to provide a `prepareForInline` function in addition to the `inlineStories` parameter.
### Customize the Docs Container
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](https://angular.io/guide/elements)).
Here’s an example of how to render Vue stories inline. The following docs config block uses `prepareForInline` and an effect hook provided by [@egoist/vue-to-react](https://github.com/egoist/vue-to-react).
The Docs Container is the component that wraps up the documentation page. It's responsible for rendering the documentation page in Storybook's UI. You can customize it by creating your own component and updating your Storybook UI configuration file (i.e., `.storybook/preview.js`) to reference it.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-preview-prepareforinline.js.mdx',
'common/storybook-preview-auto-docs-custom-docs-container.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
With this function, anyone using the docs addon for [@storybook/vue](https://github.com/storybookjs/storybook/blob/next/code/frameworks/vue-webpack5/README.md) 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.
### Override the default theme
If you come up with an elegant and flexible implementation for the `prepareForInline` function for your 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!
By default, Storybook provides two themes for the UI: `light` and `dark`. If you need to customize the theme used by the documentation to match the existing one, you can update your Storybook UI configuration file (i.e., `.storybook/preview.js`) and apply it.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-preview-auto-docs-override-theme.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
### Working with custom MDX components
Out of the box, Storybook has a set of components that you can use to customize your documentation page. If you're working with a design system or component library and wish to add them to your documentation page, you can override the `MDXProvider` component inherited from `@mdx-js/react` with your own.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-auto-docs-override-mdx-container.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
#### Learn more about Storybook documentation
- Docs for creating documentation for your stories
- [MDX](./mdx.md) for customizing your documentation
- [Publishing docs](./build-documentation.md) to automate the process of publishing your documentation

19
docs/writing-docs/introduction.md
View File

@ -4,21 +4,12 @@ title: 'How to document components'
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.
Storybook gives you tools to expand this essential 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.
<video autoPlay muted playsInline loop>
<source
src="addon-docs-optimized.mp4"
type="video/mp4"
/>
</video>
![Storybook Docs UI](./storybook-docs-ui-optimized.png)
If you're including Storybook in your project for the [first time](../get-started/install.md), we provide you with [DocsPage](./docs-page.md), 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. If you need, you can customize this page to create your own custom template.
If you're including Storybook in your project for the [first time](../get-started/install.md) or migrating from a previous version, we provide you with a [documentation page](./docs-page.md.md) ("Docs" for short), positioned near your stories. It's a baseline template automatically generated, listing your existing stories and relevant metadata.
If you're already using Storybook and you're **updating** to the latest release, we recommend that you install [@storybook/addon-essentials](https://www.npmjs.com/package/@storybook/addon-essentials), to include this and other great features into your project.
Additionally, you can customize this template if needed or create free-form pages for each component using [MDX](./mdx.md). In both cases, you’ll use Doc Blocks as the building blocks to create full-featured documentation.
You can also create free-form pages for each component using [MDX](./mdx.md), a format for simultaneously documenting components and writing stories.
In both cases, you’ll use Doc Blocks as the building blocks to create full featured documentation.
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 [here](https://storybook.js.org/addons/@storybook/addon-docs).
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 [here](https://storybook.js.org/addons/@storybook/addon-docs).

BIN
docs/writing-docs/storybook-button-auto-docs-optimized.mp4 Normal file
View File

Binary file not shown.

BIN
docs/writing-docs/storybook-docs-ui-optimized.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 259 KiB