migration guide: This page documents the method to configure Storybook introduced recently in 7.0.0, consult the migration guide if you want to migrate to this format of configuring Storybook.
Storybook Docs transforms your Storybook stories into world-class component documentation.
DocsPage. Out of the box, all your stories get a DocsPage
. DocsPage
is a zero-config aggregation of your component stories, text descriptions, docgen comments, props tables, and code examples into clean, readable pages.
MDX. If you want more control, MDX
allows you to write long-form markdown documentation and include stories in one file. You can also use it to write pure documentation pages and embed them inside your Storybook alongside your stories.
Just like Storybook, Docs supports every major view layer including React, Vue, Angular, HTML, Web components, Svelte, and many more.
Read on to learn more:
When you install Docs, every story gets a DocsPage
. DocsPage
pulls information from your stories, components, source code, and story metadata to construct a sensible, zero-config default.
Click on the Docs
tab to see it:
For more information on how it works, see the DocsPage
reference.
MDX
is a syntax for writing long-form documentation with stories side-by-side in the same file. In contrast to DocsPage
, which provides smart documentation out of the box, MDX
gives you full control over your component documentation.
Here's an example file:
import { Meta, Story, Canvas } from '@storybook/blocks';
import * as CheckboxStories from './Checkbox.stories';
<Meta title="MDX/Checkbox" of={CheckboxStories} />
# Checkbox
With `MDX` we can include a story for `Checkbox` right in the middle of our
markdown documentation.
<Canvas>
<Story of={CheckboxStories.Unchecked} />
</Canvas>
And here's how that's rendered in Storybook:
For more information on MDX
, see the MDX
reference.
Storybook Docs supports all view layers that Storybook supports except for React Native (currently). There are some framework-specific features as well, such as props tables and inline story rendering. The following page captures the current state of support:
Note: #
= WIP support
Want to add enhanced features to your favorite framework? Check out this dev guide
First add the package. Make sure that the versions for your @storybook/*
packages match:
yarn add -D @storybook/addon-docs
Docs has peer dependencies on react
. If you want to write stories in MDX, you may need to add this dependency as well:
yarn add -D react
Then add the following to your .storybook/main.js
:
module.exports = {
stories: [
'../src/**/*.mdx)', // 👈 Add this, to match your project's structure
'../src/**/*.stories.@(js|jsx|ts|tsx)',
],
addons: [
'@storybook/addon-docs', // 👈 Also add this
],
};
If using in conjunction with the storyshots add-on, you will need to configure Jest to transform MDX stories into something Storyshots can understand:
Add the following to your Jest configuration:
{
"transform": {
"^.+\\.[tj]sx?$": "babel-jest",
"^.+\\.mdx$": "@storybook/addon-docs/jest-transform-mdx"
}
}
- React (covered here)
- Vue
- Angular
- Ember
- Web Components
- Common setup (all other frameworks)
The addon-docs
preset has a few configuration options that can be used to configure its babel/webpack loading behavior. Here's an example of how to use the preset with options:
module.exports = {
addons: [
{
name: '@storybook/addon-docs',
options: {
jsxOptions: {},
csfPluginOptions: null,
transcludeMarkdown: true,
},
},
],
};
jsxOptions
are options that will be passed to @babel/preset-react
for .md
and .mdx
files.
csfPluginOptions
is an object for configuring @storybook/csf-plugin
. When set to null
it tells docs not to run the csf-plugin
at all, which can be used as an optimization, or if you're already using csf-plugin
in your main.js
.
The transcludeMarkdown
option enables mdx files to import .md
files and render them as a component.
import { Meta } from '@storybook/addon-docs';
import Changelog from '../CHANGELOG.md';
<Meta title="Changelog" />
<Changelog />
As of SB6 TypeScript is zero-config and should work with SB Docs out of the box. For advanced configuration options, refer to the Props documentation.
Want to learn more? Here are some more articles on Storybook Docs: