1 | <center>
|
2 | <img src="../docs/media/vue-hero.png" width="100%" />
|
3 | </center>
|
4 |
|
5 | <h1>Storybook Docs for Vue</h1>
|
6 |
|
7 | > migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
|
8 |
|
9 | Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for Vue supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
|
10 |
|
11 | To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the Vue specifics, read on!
|
12 |
|
13 | - [Installation](#installation)
|
14 | - [Preset options](#preset-options)
|
15 | - [DocsPage](#docspage)
|
16 | - [Props tables](#props-tables)
|
17 | - [MDX](#mdx)
|
18 | - [Inline Stories](#inline-stories)
|
19 | - [More resources](#more-resources)
|
20 |
|
21 | ## Installation
|
22 |
|
23 | First add the package. Make sure that the versions for your `@storybook/*` packages match:
|
24 |
|
25 | ```sh
|
26 | yarn add -D @storybook/addon-docs@next
|
27 | ```
|
28 |
|
29 | Then add the following to your `.storybook/main.js` addons:
|
30 |
|
31 | ```js
|
32 | module.exports = {
|
33 | addons: ['@storybook/addon-docs'],
|
34 | };
|
35 | ```
|
36 |
|
37 | ## Preset options
|
38 |
|
39 | The `addon-docs` preset for Vue has a configuration option that can be used to configure [`vue-docgen-api`](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/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:
|
40 |
|
41 | ```js
|
42 | const path = require('path');
|
43 |
|
44 | module.exports = {
|
45 | addons: [
|
46 | {
|
47 | name: '@storybook/addon-docs',
|
48 | options: {
|
49 | vueDocgenOptions: {
|
50 | alias: {
|
51 | '@': path.resolve(__dirname, '../'),
|
52 | },
|
53 | },
|
54 | },
|
55 | },
|
56 | ],
|
57 | };
|
58 | ```
|
59 |
|
60 | The `vueDocgenOptions` is an object for configuring `vue-docgen-api`. See [`vue-docgen-api`'s docs](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api#options-docgenoptions) for available configuration options.
|
61 |
|
62 | ## DocsPage
|
63 |
|
64 | When you [install docs](#installation) you should get basic [DocsPage](../docs/docspage.md) documentation automagically for all your stories, available in the `Docs` tab of the Storybook UI.
|
65 |
|
66 | ## Props tables
|
67 |
|
68 | Getting [Props tables](../docs/props-tables.md) for your components requires a few more steps. Docs for Vue relies on [`vue-docgen-loader`](https://github.com/pocka/vue-docgen-loader). It supports `props`, `events`, and `slots` as first class prop types.
|
69 |
|
70 | Finally, be sure to fill in the `component` field in your story metadata:
|
71 |
|
72 | ```ts
|
73 | import { InfoButton } from './InfoButton.vue';
|
74 |
|
75 | export default {
|
76 | title: 'InfoButton',
|
77 | component: InfoButton,
|
78 | };
|
79 | ```
|
80 |
|
81 | If you haven't upgraded from `storiesOf`, you can use a parameter to do the same thing:
|
82 |
|
83 | ```ts
|
84 | import { storiesOf } from '@storybook/vue';
|
85 | import { InfoButton } from './InfoButton.vue';
|
86 |
|
87 | storiesOf('InfoButton', module)
|
88 | .addParameters({ component: InfoButton })
|
89 | .add( ... );
|
90 | ```
|
91 |
|
92 | ## MDX
|
93 |
|
94 | [MDX](../docs/mdx.md) is a convenient way to document your components in Markdown and embed documentation components, such as stories and props tables, inline.
|
95 |
|
96 | Docs has peer dependencies on `react`. If you want to write stories in MDX, you may need to add this dependency as well:
|
97 |
|
98 | ```sh
|
99 | yarn add -D react
|
100 | ```
|
101 |
|
102 | Then update your `.storybook/main.js` to make sure you load MDX files:
|
103 |
|
104 | ```js
|
105 | module.exports = {
|
106 | stories: ['../src/stories/**/*.stories.@(js|mdx)'],
|
107 | };
|
108 | ```
|
109 |
|
110 | Finally, you can create MDX files like this:
|
111 |
|
112 | ```md
|
113 | import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
|
114 | import { InfoButton } from './InfoButton.vue';
|
115 |
|
116 | <Meta title='InfoButton' component={InfoButton} />
|
117 |
|
118 | # InfoButton
|
119 |
|
120 | Some **markdown** description, or whatever you want.
|
121 |
|
122 | <Story name='basic' height='400px'>{{
|
123 | components: { InfoButton },
|
124 | template: '<info-button label="I\'m a button!"/>',
|
125 | }}</Story>
|
126 |
|
127 | ## ArgsTable
|
128 |
|
129 | <ArgsTable of={InfoButton} />
|
130 | ```
|
131 |
|
132 | Yes, it's redundant to declare `component` twice. [Coming soon](https://github.com/storybookjs/storybook/issues/8685).
|
133 |
|
134 | ## Inline Stories
|
135 |
|
136 | Storybook Docs renders all Vue stories inside IFrames, with a default height of `60px` (configurable using the `docs.iframeHeight` story parameter).
|
137 |
|
138 | Starting in 5.3, you can also render stories inline, and in 6.0 this has become the default behavior. To render inline, update `.storybook/preview.js`:
|
139 |
|
140 | ```js
|
141 | import { addParameters } from '@storybook/vue';
|
142 |
|
143 | addParameters({
|
144 | docs: {
|
145 | inlineStories: true,
|
146 | },
|
147 | });
|
148 | ```
|
149 |
|
150 | ## More resources
|
151 |
|
152 | Want to learn more? Here are some more articles on Storybook Docs:
|
153 |
|
154 | - References: [DocsPage](../docs/docspage.md) / [MDX](../docs/mdx.md) / [FAQ](../docs/faq.md) / [Recipes](../docs/recipes.md) / [Theming](../docs/theming.md) / [Props](../docs/props-tables.md)
|
155 | - Announcements: [Vision](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a) / [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf) / [MDX](https://medium.com/storybookjs/rich-docs-with-storybook-mdx-61bc145ae7bc) / [Framework support](https://medium.com/storybookjs/storybook-docs-for-new-frameworks-b1f6090ee0ea)
|
156 | - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
|