Skip to content
Branch: master
Find file History
Pull request Compare This branch is 31 commits ahead, 358 commits behind next.
shilman Clarify and expand on addon-docs manual config (#9638)
Clarify and expand on addon-docs manual config
Latest commit 8cf3112 Jan 26, 2020
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
a11y v5.3.9 Jan 24, 2020
actions v5.3.9 Jan 24, 2020
backgrounds v5.3.9 Jan 24, 2020
centered v5.3.9 Jan 24, 2020
contexts v5.3.9 Jan 24, 2020
cssresources v5.3.9 Jan 24, 2020
design-assets v5.3.9 Jan 24, 2020
docs Clarify and expand on addon-docs manual config (#9638) Jan 26, 2020
essentials v5.3.9 Jan 24, 2020
events v5.3.9 Jan 24, 2020
google-analytics v5.3.9 Jan 24, 2020
graphql v5.3.9 Jan 24, 2020
info
jest v5.3.9 Jan 24, 2020
knobs Merge pull request #9620 from richardhuf84/next Jan 26, 2020
links v5.3.9 Jan 24, 2020
notes v5.3.9 Jan 24, 2020
ondevice-actions v5.3.9 Jan 24, 2020
ondevice-backgrounds v5.3.9 Jan 24, 2020
ondevice-knobs v5.3.9 Jan 24, 2020
ondevice-notes v5.3.9 Jan 24, 2020
options v5.3.9 Jan 24, 2020
queryparams v5.3.9 Jan 24, 2020
storyshots v5.3.9 Jan 24, 2020
storysource v5.3.9 Jan 24, 2020
viewport v5.3.9 Jan 24, 2020

README.md

Storybook Docs

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 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:

DocsPage

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

MDX is a syntax for writing long-form documentation and 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, 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.

<Preview>
  <Story name="all checkboxes">
    <form>
      <Checkbox id="Unchecked" label="Unchecked" />
      <Checkbox id="Checked" label="Checked" checked />
      <Checkbox appearance="secondary" id="second" label="Secondary" checked />
    </form>
  </Story>
</Preview>

And here's how that's rendered in Storybook:

For more information on MDX, see the MDX reference.

Framework support

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. This chart captures the current state of support:

React Vue Angular Ember Web Components HTML Svelte Preact Polymer Riot Mithril Marko
MDX stories + + + + + + + + + + + +
CSF stories + + + + + + + + + + + +
StoriesOf stories + + + + + + + + + + + +
Source + + + + + + + + + + + +
Notes / Info + + + + + + + + + + + +
Props table + + + + +
Description + + + + +
Inline stories + + +

Note: # = WIP support

Want to add enhanced features to your favorite framework? Check out this dev guide

Installation

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, react-is, and babel-loader. If you want to write stories in MDX, you may need to add these dependencies as well:

yarn add -D react react-is babel-loader

Then add the following to your .storybook/main.js:

module.exports = {
  stories: ['../src/**/*.stories.(js|mdx)'],
  addons: ['@storybook/addon-docs'],
};

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"
  }
}

Be sure to check framework specific installation needs

Preset options

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: {
        configureJSX: true,
        babelOptions: {},
        sourceLoaderOptions: null,
      },
    },
  ],
};

The configureJSX option is useful when you're writing your docs in MDX and your project's babel config isn't already set up to handle JSX files. babelOptions is a way to further configure the babel processor when you're using configureJSX.

sourceLoaderOptions is an object for configuring @storybook/source-loader. When set to null it tells docs not to run the source-loader at all, which can be used as an optimization, or if you're already using source-loader in your main.js.

Manual configuration

If you don't want to use the preset, and prefer to configure "the long way" add the following configuration to .storybook/main.js (see comments inline for explanation):

const createCompiler = require('@storybook/addon-docs/mdx-compiler-plugin');

module.exports = {
  // 1. register the docs panel (as opposed to '@storybook/addon-docs' which
  //    will configure everything with a preset)
  addons: ['@storybook/addon-docs/register'],
  // 2. manually configure webpack, since you're not using the preset
  webpackFinal: async config => {
    config.module.rules.push({
      // 2a. Load `.stories.mdx` / `.story.mdx` files as CSF and generate
      //     the docs page from the markdown
      test: /\.(stories|story)\.mdx$/,
      use: [
        {
          loader: 'babel-loader',
          // may or may not need this line depending on your app's setup
          options: {
            plugins: ['@babel/plugin-transform-react-jsx'],
          },
        },
        {
          loader: '@mdx-js/loader',
          options: {
            compilers: [createCompiler({})],
          },
        },
      ],
    });
    // 2b. Run `source-loader` on story files to show their source code
    //     automatically in `DocsPage` or the `Source` doc block.
    config.module.rules.push({
      test: /\.(stories|story)\.[tj]sx?$/,
      loader: require.resolve('@storybook/source-loader'),
      exclude: [/node_modules/],
      enforce: 'pre',
    });
    return config;
  },
};

Finally, you'll need to set up DocsPage in .storybook/preview.js:

import { addParameters } from '@storybook/react';
import { DocsPage, DocsContainer } from '@storybook/addon-docs/blocks';

addParameters({
  docs: {
    container: DocsContainer,
    page: DocsPage,
  },
});

TypeScript configuration

SB Docs for React uses babel-plugin-react-docgen to extract Docgen comments from your code automatically. However, if you're using TypeScript, some extra configuration maybe required to get this information included in your docs.

  1. You can add react-docgen-typescript-loader to your project by following the instructions there.
  2. You can use @storybook/preset-typescript which includes react-docgen-typescript-loader.

Install the preset with care. If you've already configured Typescript manually, that configuration may conflict with the preset. You can debug your final webpack configuration with --debug-webpack.

More resources

Want to learn more? Here are some more articles on Storybook Docs:

You can’t perform that action at this time.