1 | <h1>Storybook Docs Common Setup</h1>
|
2 |
|
3 | Storybook Docs transforms your Storybook stories into world-class component documentation. Docs supports [all web frameworks that Storybook supports](../README.md#framework-support).
|
4 |
|
5 | Popular frameworks like [React](../react/README.md)/[Vue](../vue/README.md)/[Angular](../angular/README.md)/[Ember](../ember/README.md)/[Web components](../web-components/README.md) have their own framework-specific optimizations and setup guides. This README documents the "common" setup for other frameworks that don't have any docs-specific optimizations.
|
6 |
|
7 | - [Installation](#installation)
|
8 | - [DocsPage](#docspage)
|
9 | - [MDX](#mdx)
|
10 | - [IFrame height](#iframe-height)
|
11 | - [More resources](#more-resources)
|
12 |
|
13 | ## Installation
|
14 |
|
15 | First add the package. Make sure that the versions for your `@storybook/*` packages match:
|
16 |
|
17 | ```sh
|
18 | yarn add -D @storybook/addon-docs@next
|
19 | ```
|
20 |
|
21 | Then add the following to your `.storybook/main.js` addons:
|
22 |
|
23 | ```js
|
24 | module.exports = {
|
25 | addons: ['@storybook/addon-docs'],
|
26 | };
|
27 | ```
|
28 |
|
29 | ## DocsPage
|
30 |
|
31 | 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.
|
32 |
|
33 | ## MDX
|
34 |
|
35 | [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.
|
36 |
|
37 | Docs has peer dependencies on `react`. If you want to write stories in MDX, you may need to add this dependency as well:
|
38 |
|
39 | ```sh
|
40 | yarn add -D react
|
41 | ```
|
42 |
|
43 | Then update your `.storybook/main.js` to make sure you load MDX files:
|
44 |
|
45 | ```js
|
46 | module.exports = {
|
47 | stories: ['../src/stories/**/*.stories.@(js|mdx)'],
|
48 | };
|
49 | ```
|
50 |
|
51 | Finally, you can create MDX files like this:
|
52 |
|
53 | ```md
|
54 | import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
|
55 |
|
56 | <Meta title='App Component' />
|
57 |
|
58 | # App Component
|
59 |
|
60 | Some **markdown** description, or whatever you want.
|
61 |
|
62 | <Story name='basic' height='400px'>{() => {
|
63 | return { ... }; // should match the typical story format for your framework
|
64 | }}</Story>
|
65 | ```
|
66 |
|
67 | ## IFrame height
|
68 |
|
69 | In the "common" setup, Storybook Docs renders stories inside `iframe`s, with a default height of `60px`. You can update this default globally, or modify the `iframe` height locally per story in `DocsPage` and `MDX`.
|
70 |
|
71 | To update the global default, modify `.storybook/preview.js`:
|
72 |
|
73 | ```ts
|
74 | import { addParameters } from '@storybook/ember';
|
75 |
|
76 | addParameters({ docs: { iframeHeight: 400 } });
|
77 | ```
|
78 |
|
79 | For `DocsPage`, you need to update the parameter locally in a story:
|
80 |
|
81 | ```ts
|
82 | export const basic = () => ...
|
83 | basic.parameters = {
|
84 | docs: { iframeHeight: 400 }
|
85 | }
|
86 | ```
|
87 |
|
88 | And for `MDX` you can modify it, especially if you work with some components using fixed or sticky positions, as an attribute on the `Story` element:
|
89 |
|
90 | ```md
|
91 | <Story name='basic' height='400px'>{...}</Story>
|
92 | ```
|
93 |
|
94 | ## More resources
|
95 |
|
96 | Want to learn more? Here are some more articles on Storybook Docs:
|
97 |
|
98 | - 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)
|
99 | - 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)
|
100 | - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
|