Skip to content

Latest commit

 

History

History
152 lines (104 loc) · 5.11 KB

README.md

File metadata and controls

152 lines (104 loc) · 5.11 KB
Raw

Storybook Docs for Vue

migration guide: This page documents the method to configure storybook introduced recently in 5.3.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. Storybook Docs for Vue supports DocsPage for auto-generated docs, and MDX for rich long-form docs.

To learn more about Storybook Docs, read the general documentation. To learn the Vue specifics, read on!

Installation

First add the package. Make sure that the versions for your @storybook/* packages match:

yarn add -D @storybook/addon-docs

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

export default {
  addons: ['@storybook/addon-docs'],
};

Preset options

The addon-docs preset for Vue has a configuration option that can be used to configure vue-docgen-api, a tool which extracts information from Vue components. Here's an example of how to use the preset with options for Vue app:

import * as path from 'path';

export default {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        vueDocgenOptions: {
          alias: {
            '@': path.resolve(__dirname, '../'),
          },
        },
      },
    },
  ],
};

The vueDocgenOptions is an object for configuring vue-docgen-api. See vue-docgen-api's docs for available configuration options.

DocsPage

When you install docs you should get basic DocsPage documentation automagically for all your stories, available in the Docs tab of the Storybook UI.

Props tables

Getting Props tables for your components requires a few more steps. Docs for Vue relies on vue-docgen-loader. It supports props, events, and slots as first class prop types.

Finally, be sure to fill in the component field in your story metadata:

import { InfoButton } from './InfoButton.vue';

export default {
  title: 'InfoButton',
  component: InfoButton,
};

If you haven't upgraded from storiesOf, you can use a parameter to do the same thing:

import { storiesOf } from '@storybook/vue';
import { InfoButton } from './InfoButton.vue';

storiesOf('InfoButton', module)
  .addParameters({ component: InfoButton })
  .add( ... );

MDX

MDX is a convenient way to document your components in Markdown and embed documentation components, such as stories and props tables, inline.

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 update your .storybook/main.js to make sure you load MDX files:

export default {
  stories: ['../src/stories/**/*.stories.@(js|mdx)'],
};

Finally, you can create MDX files like this:

import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
import { InfoButton } from './InfoButton.vue';

<Meta title='InfoButton' component={InfoButton} />

# InfoButton

Some **markdown** description, or whatever you want.

<Story name='basic' height='400px'>{{
  components: { InfoButton },
  template: '<info-button label="I\'m a button!"/>',
}}</Story>

## ArgsTable

<ArgsTable of={InfoButton} />

Yes, it's redundant to declare component twice. Coming soon.

Inline Stories

Storybook Docs renders all Vue stories inline by default.

However, you can render stories in an iframe, with a default height of 60px (configurable using the docs.story.iframeHeight story parameter), by using the docs.stories.inline parameter.

To do so for all stories, update .storybook/preview.js:

export const parameters = { docs: { story: { inline: false } } };

More resources

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