@storybook/addon-docs 0.0.0-pr-23609-sha-f47ef339
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +181 -0
- package/angular/README.md +256 -0
- package/angular/index.d.ts +1 -0
- package/angular/index.js +7 -0
- package/common/README.md +98 -0
- package/dist/DocsRenderer-3PUGWF3O.mjs +1 -0
- package/dist/blocks.d.ts +2 -0
- package/dist/blocks.js +1 -0
- package/dist/blocks.mjs +4 -0
- package/dist/chunk-S4VUQJ4A.mjs +7 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +1 -0
- package/dist/index.mjs +2 -0
- package/dist/preset.d.ts +8 -0
- package/dist/preset.js +40 -0
- package/dist/preview.d.ts +3 -0
- package/dist/preview.js +1 -0
- package/dist/preview.mjs +3 -0
- package/dist/shims/mdx-react-shim.d.ts +1 -0
- package/dist/shims/mdx-react-shim.js +1 -0
- package/dist/shims/mdx-react-shim.mjs +1 -0
- package/ember/README.md +152 -0
- package/ember/index.js +6 -0
- package/jest-transform-mdx.js +22 -0
- package/jest.config.js +7 -0
- package/package.json +152 -0
- package/postinstall/presets.js +36 -0
- package/preset.js +1 -0
- package/preview.js +2 -0
- package/react/README.md +177 -0
- package/src/typings.d.ts +15 -0
- package/svelte/HOC.svelte +7 -0
- package/template/stories/stories-mdx/csf-in-mdx.non-stories.js +19 -0
- package/vue/README.md +152 -0
- package/vue3/README.md +152 -0
- package/web-components/README.md +131 -0
- package/web-components/index.js +1 -0
package/README.md
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
<center>
|
|
2
|
+
<img src="https://raw.githubusercontent.com/storybookjs/storybook/next/code/addons/docs/docs/media/hero.png" width="100%" />
|
|
3
|
+
</center>
|
|
4
|
+
|
|
5
|
+
# Storybook Docs
|
|
6
|
+
|
|
7
|
+
> migration guide: This page documents the method to configure Storybook introduced recently in 7.0.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.
|
|
10
|
+
|
|
11
|
+
**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.
|
|
12
|
+
|
|
13
|
+
**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.
|
|
14
|
+
|
|
15
|
+
Just like Storybook, Docs supports every major view layer including React, Vue, Angular, HTML, Web components, Svelte, and many more.
|
|
16
|
+
|
|
17
|
+
Read on to learn more:
|
|
18
|
+
|
|
19
|
+
- [Storybook Docs](#storybook-docs)
|
|
20
|
+
- [DocsPage](#docspage)
|
|
21
|
+
- [MDX](#mdx)
|
|
22
|
+
- [Framework support](#framework-support)
|
|
23
|
+
- [Installation](#installation)
|
|
24
|
+
- [Be sure to check framework specific installation needs](#be-sure-to-check-framework-specific-installation-needs)
|
|
25
|
+
- [Preset options](#preset-options)
|
|
26
|
+
- [TypeScript configuration](#typescript-configuration)
|
|
27
|
+
- [More resources](#more-resources)
|
|
28
|
+
|
|
29
|
+
## DocsPage
|
|
30
|
+
|
|
31
|
+
When you [install Docs](#installation), every story gets a `DocsPage`. `DocsPage` pulls information from your stories, components, source code, and story metadata to construct a sensible, zero-config default.
|
|
32
|
+
|
|
33
|
+
Click on the `Docs` tab to see it:
|
|
34
|
+
|
|
35
|
+
<center>
|
|
36
|
+
<img src="https://raw.githubusercontent.com/storybookjs/storybook/next/code/addons/docs/docs/media/docs-tab.png" width="100%" />
|
|
37
|
+
</center>
|
|
38
|
+
|
|
39
|
+
For more information on how it works, see the [`DocsPage` reference](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/docs/docspage.md).
|
|
40
|
+
|
|
41
|
+
## MDX
|
|
42
|
+
|
|
43
|
+
`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.
|
|
44
|
+
|
|
45
|
+
Here's an example file:
|
|
46
|
+
|
|
47
|
+
<!-- prettier-ignore-start -->
|
|
48
|
+
|
|
49
|
+
```md
|
|
50
|
+
import { Meta, Story, Canvas } from '@storybook/blocks';
|
|
51
|
+
import * as CheckboxStories from './Checkbox.stories';
|
|
52
|
+
|
|
53
|
+
<Meta title="MDX/Checkbox" of={CheckboxStories} />
|
|
54
|
+
|
|
55
|
+
# Checkbox
|
|
56
|
+
|
|
57
|
+
With `MDX` we can include a story for `Checkbox` right in the middle of our
|
|
58
|
+
markdown documentation.
|
|
59
|
+
|
|
60
|
+
<Canvas>
|
|
61
|
+
<Story of={CheckboxStories.Unchecked} />
|
|
62
|
+
</Canvas>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
<!-- prettier-ignore-end -->
|
|
66
|
+
|
|
67
|
+
And here's how that's rendered in Storybook:
|
|
68
|
+
|
|
69
|
+
<center>
|
|
70
|
+
<img src="https://raw.githubusercontent.com/storybookjs/storybook/next/code/addons/docs/docs/media/mdx-simple.png" width="100%" />
|
|
71
|
+
</center>
|
|
72
|
+
|
|
73
|
+
For more information on `MDX`, see the [`MDX` reference](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/docs/mdx.md).
|
|
74
|
+
|
|
75
|
+
## Framework support
|
|
76
|
+
|
|
77
|
+
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:
|
|
78
|
+
|
|
79
|
+
[Framework Support](https://storybook.js.org/docs/react/api/frameworks-feature-support)
|
|
80
|
+
|
|
81
|
+
**Note:** `#` = WIP support
|
|
82
|
+
|
|
83
|
+
Want to add enhanced features to your favorite framework? Check out this [dev guide](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/multiframework.md)
|
|
84
|
+
|
|
85
|
+
## Installation
|
|
86
|
+
|
|
87
|
+
First add the package. Make sure that the versions for your `@storybook/*` packages match:
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
yarn add -D @storybook/addon-docs
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Docs has peer dependencies on `react`. If you want to write stories in MDX, you may need to add this dependency as well:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
yarn add -D react
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Then add the following to your `.storybook/main.js`:
|
|
100
|
+
|
|
101
|
+
```js
|
|
102
|
+
export default {
|
|
103
|
+
stories: [
|
|
104
|
+
'../src/**/*.mdx', // 👈 Add this, to match your project's structure
|
|
105
|
+
'../src/**/*.stories.@(js|jsx|ts|tsx)',
|
|
106
|
+
],
|
|
107
|
+
addons: [
|
|
108
|
+
'@storybook/addon-docs', // 👈 Also add this
|
|
109
|
+
],
|
|
110
|
+
};
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
If using in conjunction with the [storyshots add-on](https://github.com/storybookjs/storybook/blob/next/code/addons/storyshots-core/README.md), you will need to
|
|
114
|
+
configure Jest to transform MDX stories into something Storyshots can understand:
|
|
115
|
+
|
|
116
|
+
Add the following to your Jest configuration:
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"transform": {
|
|
121
|
+
"^.+\\.[tj]sx?$": "babel-jest",
|
|
122
|
+
"^.+\\.mdx$": "@storybook/addon-docs/jest-transform-mdx"
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Be sure to check framework specific installation needs
|
|
128
|
+
|
|
129
|
+
- [React](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/react) (covered here)
|
|
130
|
+
- [Vue](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/vue)
|
|
131
|
+
- [Angular](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/angular)
|
|
132
|
+
- [Ember](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/ember)
|
|
133
|
+
- [Web Components](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/web-components)
|
|
134
|
+
- [Common setup (all other frameworks)](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/common)
|
|
135
|
+
|
|
136
|
+
## Preset options
|
|
137
|
+
|
|
138
|
+
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:
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
export default {
|
|
142
|
+
addons: [
|
|
143
|
+
{
|
|
144
|
+
name: '@storybook/addon-docs',
|
|
145
|
+
options: {
|
|
146
|
+
jsxOptions: {},
|
|
147
|
+
csfPluginOptions: null,
|
|
148
|
+
mdxPluginOptions: {},
|
|
149
|
+
transcludeMarkdown: true,
|
|
150
|
+
},
|
|
151
|
+
},
|
|
152
|
+
],
|
|
153
|
+
};
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`jsxOptions` are options that will be passed to `@babel/preset-react` for `.md` and `.mdx` files.
|
|
157
|
+
|
|
158
|
+
`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`.
|
|
159
|
+
|
|
160
|
+
The `transcludeMarkdown` option enables mdx files to import `.md` files and render them as a component.
|
|
161
|
+
|
|
162
|
+
```mdx
|
|
163
|
+
import { Meta } from '@storybook/addon-docs';
|
|
164
|
+
import Changelog from '../CHANGELOG.md';
|
|
165
|
+
|
|
166
|
+
<Meta title="Changelog" />
|
|
167
|
+
|
|
168
|
+
<Changelog />
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## TypeScript configuration
|
|
172
|
+
|
|
173
|
+
As of SB6 [TypeScript is zero-config](https://storybook.js.org/docs/react/configure/typescript) and should work with SB Docs out of the box. For advanced configuration options, refer to the [Props documentation](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/props-tables.md).
|
|
174
|
+
|
|
175
|
+
## More resources
|
|
176
|
+
|
|
177
|
+
Want to learn more? Here are some more articles on Storybook Docs:
|
|
178
|
+
|
|
179
|
+
- References: [DocsPage](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/docspage.md) / [MDX](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/mdx.md) / [FAQ](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/faq.md) / [Recipes](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/recipes.md) / [Theming](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/theming.md) / [Props](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/props-tables.md)
|
|
180
|
+
- 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)
|
|
181
|
+
- Example: [Storybook Design System](https://github.com/storybookjs/design-system)
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
<center>
|
|
2
|
+
<img src="../docs/media/angular-hero.png" width="100%" />
|
|
3
|
+
</center>
|
|
4
|
+
|
|
5
|
+
<h1>Storybook Docs for Angular</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 Angular 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 Angular specifics, read on!
|
|
12
|
+
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
- [DocsPage](#docspage)
|
|
15
|
+
- [Props tables](#props-tables)
|
|
16
|
+
- [Automatic Compodoc setup](#automatic-compodoc-setup)
|
|
17
|
+
- [Manual Compodoc setup](#manual-compodoc-setup)
|
|
18
|
+
- [MDX](#mdx)
|
|
19
|
+
- [IFrame height](#iframe-height)
|
|
20
|
+
- [Inline Stories](#inline-stories)
|
|
21
|
+
- [More resources](#more-resources)
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
First add the package. Make sure that the versions for your `@storybook/*` packages match:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
yarn add -D @storybook/addon-docs
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Then add the following to your `.storybook/main.js` exports:
|
|
32
|
+
|
|
33
|
+
```js
|
|
34
|
+
export default {
|
|
35
|
+
addons: ['@storybook/addon-docs'],
|
|
36
|
+
};
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## DocsPage
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
## Props tables
|
|
44
|
+
|
|
45
|
+
Getting [Props tables](../docs/props-tables.md) for your components requires a few more steps. Docs for Angular relies on [Compodoc](https://compodoc.app/), the excellent API documentation tool. It supports `inputs`, `outputs`, `properties`, `methods`, `view/content child/children` as first class prop types.
|
|
46
|
+
|
|
47
|
+
### Automatic Compodoc setup
|
|
48
|
+
|
|
49
|
+
During `sb init`, you will be asked, whether you want to setup Compodoc for your project. Just answer the question with Yes. Compodoc is then ready to use!
|
|
50
|
+
|
|
51
|
+
## Manual Compodoc setup
|
|
52
|
+
|
|
53
|
+
You'll need to register Compodoc's `documentation.json` file in `.storybook/preview.ts`:
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
import { setCompodocJson } from '@storybook/addon-docs/angular';
|
|
57
|
+
import docJson from '../documentation.json';
|
|
58
|
+
|
|
59
|
+
setCompodocJson(docJson);
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Finally, to set up compodoc, you'll first need to install Compodoc:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
yarn add -D @compodoc/compodoc
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Then you'll need to configure Compodoc to generate a `documentation.json` file. Adding the following snippet to your `projects.<project>.architect.<storybook|build-storybook>` in the `angular.json` creates a metadata file `./documentation.json` each time you run storybook:
|
|
69
|
+
|
|
70
|
+
```jsonc
|
|
71
|
+
// angular.json
|
|
72
|
+
{
|
|
73
|
+
"projects": {
|
|
74
|
+
"your-project": {
|
|
75
|
+
"architect": {
|
|
76
|
+
"storybook": {
|
|
77
|
+
...,
|
|
78
|
+
"compodoc": true,
|
|
79
|
+
"compodocArgs": [
|
|
80
|
+
"-e",
|
|
81
|
+
"json",
|
|
82
|
+
"-d",
|
|
83
|
+
"." // the root folder of your project
|
|
84
|
+
],
|
|
85
|
+
},
|
|
86
|
+
"build-storybook": {
|
|
87
|
+
...,
|
|
88
|
+
"compodoc": true,
|
|
89
|
+
"compodocArgs": [
|
|
90
|
+
"-e",
|
|
91
|
+
"json",
|
|
92
|
+
"-d",
|
|
93
|
+
"." // the root folder of your project
|
|
94
|
+
],
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Unfortunately, it's not currently possible to update this dynamically as you edit your components, but [there's an open issue](https://github.com/storybookjs/storybook/issues/8672) to support this with improvements to Compodoc.
|
|
103
|
+
|
|
104
|
+
Finally, be sure to fill in the `component` field in your story metadata:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
import { AppComponent } from './app.component';
|
|
108
|
+
|
|
109
|
+
export default {
|
|
110
|
+
title: 'App Component',
|
|
111
|
+
component: AppComponent,
|
|
112
|
+
};
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
If you haven't upgraded from `storiesOf`, you can use a parameter to do the same thing:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { storiesOf } from '@storybook/angular';
|
|
119
|
+
import { AppComponent } from './app.component';
|
|
120
|
+
|
|
121
|
+
storiesOf('App Component', module)
|
|
122
|
+
.addParameters({ component: AppComponent })
|
|
123
|
+
.add( ... );
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## MDX
|
|
127
|
+
|
|
128
|
+
[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.
|
|
129
|
+
|
|
130
|
+
Docs has peer dependencies on `react`. If you want to write stories in MDX, you may need to add this dependency as well:
|
|
131
|
+
|
|
132
|
+
```sh
|
|
133
|
+
yarn add -D react
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Then update your `.storybook/main.js` to make sure you load MDX files:
|
|
137
|
+
|
|
138
|
+
```js
|
|
139
|
+
export default {
|
|
140
|
+
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
|
|
141
|
+
};
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Finally, you can create MDX files like this:
|
|
145
|
+
|
|
146
|
+
```md
|
|
147
|
+
import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
|
|
148
|
+
import { AppComponent } from './app.component';
|
|
149
|
+
|
|
150
|
+
<Meta title='App Component' component={AppComponent} />
|
|
151
|
+
|
|
152
|
+
# App Component
|
|
153
|
+
|
|
154
|
+
Some **markdown** description, or whatever you want.
|
|
155
|
+
|
|
156
|
+
<Story name='basic' height='400px'>{{
|
|
157
|
+
component: AppComponent,
|
|
158
|
+
props: {},
|
|
159
|
+
}}</Story>
|
|
160
|
+
|
|
161
|
+
## ArgsTable
|
|
162
|
+
|
|
163
|
+
<ArgsTable of={AppComponent} />
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Yes, it's redundant to declare `component` twice. [Coming soon](https://github.com/storybookjs/storybook/issues/8673).
|
|
167
|
+
|
|
168
|
+
Also, to use the `Props` doc block, you need to set up Compodoc, [as described above](#docspage).
|
|
169
|
+
|
|
170
|
+
When you are using `template`, `moduleMetadata` and/or `addDecorators` with `storiesOf` then you can easily translate your story to MDX, too:
|
|
171
|
+
|
|
172
|
+
```md
|
|
173
|
+
import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
|
|
174
|
+
import { CheckboxComponent, RadioButtonComponent } from './my-components';
|
|
175
|
+
import { moduleMetadata } from '@storybook/angular';
|
|
176
|
+
|
|
177
|
+
<Meta title='Checkbox' decorators={[
|
|
178
|
+
moduleMetadata({
|
|
179
|
+
declarations: [CheckboxComponent]
|
|
180
|
+
})
|
|
181
|
+
]} />
|
|
182
|
+
|
|
183
|
+
# Basic Checkbox
|
|
184
|
+
|
|
185
|
+
<Story name='basic check' height='400px'>{{
|
|
186
|
+
template: `
|
|
187
|
+
<div class="some-wrapper-with-padding">
|
|
188
|
+
<my-checkbox [checked]="checked">Some Checkbox</my-checkbox>
|
|
189
|
+
</div>
|
|
190
|
+
`,
|
|
191
|
+
props: {
|
|
192
|
+
checked: true
|
|
193
|
+
}
|
|
194
|
+
}}</Story>
|
|
195
|
+
|
|
196
|
+
# Basic Radiobutton
|
|
197
|
+
|
|
198
|
+
<Story name='basic radio' height='400px'>{{
|
|
199
|
+
moduleMetadata: {
|
|
200
|
+
declarations: [RadioButtonComponent]
|
|
201
|
+
}
|
|
202
|
+
template: `
|
|
203
|
+
<div class="some-wrapper-with-padding">
|
|
204
|
+
<my-radio-btn [checked]="checked">Some Checkbox</my-radio-btn>
|
|
205
|
+
</div>
|
|
206
|
+
`,
|
|
207
|
+
props: {
|
|
208
|
+
checked: true
|
|
209
|
+
}
|
|
210
|
+
}}</Story>
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## IFrame height
|
|
214
|
+
|
|
215
|
+
Storybook Docs renders all Angular stories inside IFrames, with a default height of `60px`. You can update this default globally, or modify the IFrame height locally per story in `DocsPage` and `MDX`.
|
|
216
|
+
|
|
217
|
+
To update the global default, modify `.storybook/preview.ts`:
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
export const parameters = { docs: { story: { iframeHeight: '400px' } } };
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
For `DocsPage`, you need to update the parameter locally in a story:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
export const basic = () => ...
|
|
227
|
+
basic.parameters = {
|
|
228
|
+
docs: { story: { iframeHeight: '400px' } },
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
And for `MDX` you can modify it as an attribute on the `Story` element:
|
|
233
|
+
|
|
234
|
+
```md
|
|
235
|
+
<Story name='basic' height='400px'>{...}</Story>
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Inline Stories
|
|
239
|
+
|
|
240
|
+
Storybook Docs renders all Angular stories inline by default.
|
|
241
|
+
|
|
242
|
+
However, you can render stories in an iframe, with a default height of `100px` (configurable using the `docs.story.iframeHeight` story parameter), by using the `docs.story.inline` parameter.
|
|
243
|
+
|
|
244
|
+
To do so for all stories, update `.storybook/preview.js`:
|
|
245
|
+
|
|
246
|
+
```js
|
|
247
|
+
export const parameters = { docs: { story: { inline: false } } };
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## More resources
|
|
251
|
+
|
|
252
|
+
Want to learn more? Here are some more articles on Storybook Docs:
|
|
253
|
+
|
|
254
|
+
- 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)
|
|
255
|
+
- 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)
|
|
256
|
+
- Example: [Storybook Design System](https://github.com/storybookjs/design-system)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const setCompodocJson: (compodocJson: any) => void;
|
package/angular/index.js
ADDED
package/common/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
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
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Then add the following to your `.storybook/main.js` addons:
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
export default {
|
|
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
|
+
export default {
|
|
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
|
+
export const parameters = { docs: { story: { iframeHeight: '400px' } } };
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
For `DocsPage`, you need to update the parameter locally in a story:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
export const basic = () => ...
|
|
81
|
+
basic.parameters = {
|
|
82
|
+
docs: { story: { iframeHeight: '400px' } }
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
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:
|
|
87
|
+
|
|
88
|
+
```md
|
|
89
|
+
<Story name='basic' height='400px'>{...}</Story>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## More resources
|
|
93
|
+
|
|
94
|
+
Want to learn more? Here are some more articles on Storybook Docs:
|
|
95
|
+
|
|
96
|
+
- 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)
|
|
97
|
+
- 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)
|
|
98
|
+
- Example: [Storybook Design System](https://github.com/storybookjs/design-system)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { DocsRenderer, defaultComponents } from './chunk-S4VUQJ4A.mjs';
|
package/dist/blocks.d.ts
ADDED
package/dist/blocks.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;var __copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to},__reExport=(target,mod,secondTarget)=>(__copyProps(target,mod,"default"),secondTarget&&__copyProps(secondTarget,mod,"default"));var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:!0}),mod);var blocks_exports={};module.exports=__toCommonJS(blocks_exports);var import_client_logger=require("@storybook/client-logger");__reExport(blocks_exports,require("@storybook/blocks"),module.exports);(0,import_client_logger.deprecate)("Import from '@storybook/addon-docs/blocks' is deprecated. Please import from '@storybook/blocks' instead.");0&&(module.exports={...require("@storybook/blocks")});
|
package/dist/blocks.mjs
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import React, { Component } from 'react';
|
|
2
|
+
import { renderElement, unmountElement } from '@storybook/react-dom-shim';
|
|
3
|
+
import { CodeOrSourceMdx, AnchorMdx, HeadersMdx, Docs } from '@storybook/blocks';
|
|
4
|
+
|
|
5
|
+
var defaultComponents={code:CodeOrSourceMdx,a:AnchorMdx,...HeadersMdx},ErrorBoundary=class extends Component{constructor(){super(...arguments);this.state={hasError:!1};}static getDerivedStateFromError(){return {hasError:!0}}componentDidCatch(err){let{showException}=this.props;showException(err);}render(){let{hasError}=this.state,{children}=this.props;return hasError?null:children}},DocsRenderer=class{constructor(){this.render=async(context,docsParameter,element)=>{let components={...defaultComponents,...docsParameter?.components},TDocs=Docs;return new Promise((resolve,reject)=>{import('@mdx-js/react').then(({MDXProvider})=>renderElement(React.createElement(ErrorBoundary,{showException:reject,key:Math.random()},React.createElement(MDXProvider,{components},React.createElement(TDocs,{context,docsParameter}))),element)).then(()=>resolve());})},this.unmount=element=>{unmountElement(element);};}};
|
|
6
|
+
|
|
7
|
+
export { DocsRenderer, defaultComponents };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export * from '@storybook/blocks';
|
|
2
|
+
import { Renderer, DocsRenderFunction } from '@storybook/types';
|
|
3
|
+
|
|
4
|
+
declare class DocsRenderer<TRenderer extends Renderer> {
|
|
5
|
+
render: DocsRenderFunction<TRenderer>;
|
|
6
|
+
unmount: (element: HTMLElement) => void;
|
|
7
|
+
constructor();
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
export { DocsRenderer };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";var __create=Object.create;var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __getProtoOf=Object.getPrototypeOf,__hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:!0})},__copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to},__reExport=(target,mod,secondTarget)=>(__copyProps(target,mod,"default"),secondTarget&&__copyProps(secondTarget,mod,"default")),__toESM=(mod,isNodeMode,target)=>(target=mod!=null?__create(__getProtoOf(mod)):{},__copyProps(isNodeMode||!mod||!mod.__esModule?__defProp(target,"default",{value:mod,enumerable:!0}):target,mod)),__toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:!0}),mod);var src_exports={};__export(src_exports,{DocsRenderer:()=>DocsRenderer});module.exports=__toCommonJS(src_exports);__reExport(src_exports,require("@storybook/blocks"),module.exports);var import_react=__toESM(require("react")),import_react_dom_shim=require("@storybook/react-dom-shim"),import_blocks=require("@storybook/blocks"),defaultComponents={code:import_blocks.CodeOrSourceMdx,a:import_blocks.AnchorMdx,...import_blocks.HeadersMdx},ErrorBoundary=class extends import_react.Component{constructor(){super(...arguments);this.state={hasError:!1}}static getDerivedStateFromError(){return{hasError:!0}}componentDidCatch(err){let{showException}=this.props;showException(err)}render(){let{hasError}=this.state,{children}=this.props;return hasError?null:children}},DocsRenderer=class{constructor(){this.render=async(context,docsParameter,element)=>{let components={...defaultComponents,...docsParameter==null?void 0:docsParameter.components},TDocs=import_blocks.Docs;return new Promise((resolve,reject)=>{import("@mdx-js/react").then(({MDXProvider})=>(0,import_react_dom_shim.renderElement)(import_react.default.createElement(ErrorBoundary,{showException:reject,key:Math.random()},import_react.default.createElement(MDXProvider,{components},import_react.default.createElement(TDocs,{context,docsParameter}))),element)).then(()=>resolve())})},this.unmount=element=>{(0,import_react_dom_shim.unmountElement)(element)}}};0&&(module.exports={DocsRenderer,...require("@storybook/blocks")});
|
package/dist/index.mjs
ADDED
package/dist/preset.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { StorybookConfig } from '@storybook/types';
|
|
2
|
+
|
|
3
|
+
declare const addons: StorybookConfig['addons'];
|
|
4
|
+
declare const webpackX: any;
|
|
5
|
+
declare const storyIndexersX: any;
|
|
6
|
+
declare const docsX: any;
|
|
7
|
+
|
|
8
|
+
export { addons, docsX as docs, storyIndexersX as storyIndexers, webpackX as webpack };
|
package/dist/preset.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"use strict";var __create=Object.create;var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __getProtoOf=Object.getPrototypeOf,__hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:!0})},__copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to};var __toESM=(mod,isNodeMode,target)=>(target=mod!=null?__create(__getProtoOf(mod)):{},__copyProps(isNodeMode||!mod||!mod.__esModule?__defProp(target,"default",{value:mod,enumerable:!0}):target,mod)),__toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:!0}),mod);var preset_exports={};__export(preset_exports,{addons:()=>addons,docs:()=>docsX,storyIndexers:()=>storyIndexersX,webpack:()=>webpackX});module.exports=__toCommonJS(preset_exports);var import_fs_extra=__toESM(require("fs-extra")),import_remark_slug=__toESM(require("remark-slug")),import_remark_external_links=__toESM(require("remark-external-links")),import_ts_dedent2=require("ts-dedent"),import_global=require("@storybook/global"),import_csf_tools=require("@storybook/csf-tools"),import_node_logger2=require("@storybook/node-logger");var import_node_logger=require("@storybook/node-logger"),import_ts_dedent=__toESM(require("ts-dedent"));function ensureReactPeerDeps(){try{require.resolve("react"),require.resolve("react-dom")}catch{import_node_logger.logger.error(import_ts_dedent.default`
|
|
2
|
+
Starting in 7.0, react and react-dom are now required peer dependencies of Storybook.
|
|
3
|
+
https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#react-peer-dependencies-required
|
|
4
|
+
|
|
5
|
+
It seems that you haven't run Storybook's CLI to upgrade to the latest version.
|
|
6
|
+
The upgrade command will install the required peer dependencies for you and will take
|
|
7
|
+
care of other important auto migrations as well.
|
|
8
|
+
|
|
9
|
+
If you want to upgrade to the latest prerelease version, please run:
|
|
10
|
+
|
|
11
|
+
$ npx storybook@next upgrade --prerelease
|
|
12
|
+
|
|
13
|
+
Otherwise, please run:
|
|
14
|
+
|
|
15
|
+
$ npx storybook upgrade
|
|
16
|
+
|
|
17
|
+
If you do not want to use the upgrade commands,
|
|
18
|
+
please install react and react-dom in your project manually.
|
|
19
|
+
|
|
20
|
+
npm:
|
|
21
|
+
$ npm add react react-dom --dev
|
|
22
|
+
|
|
23
|
+
yarn:
|
|
24
|
+
$ yarn add react react-dom --dev
|
|
25
|
+
|
|
26
|
+
pnpm:
|
|
27
|
+
$ pnpm add react react-dom --dev
|
|
28
|
+
`),process.exit(1)}}async function webpack(webpackConfig={},options){var _a,_b,_c;let{module:module2={}}=webpackConfig,{csfPluginOptions={},jsxOptions={},sourceLoaderOptions=null,configureJsx,mdxBabelOptions,mdxPluginOptions={}}=options,mdxLoaderOptions=await options.presets.apply("mdxLoaderOptions",{skipCsf:!0,...mdxPluginOptions,mdxCompileOptions:{providerImportSource:"@storybook/addon-docs/mdx-react-shim",...mdxPluginOptions.mdxCompileOptions,remarkPlugins:[import_remark_slug.default,import_remark_external_links.default].concat(((_a=mdxPluginOptions==null?void 0:mdxPluginOptions.mdxCompileOptions)==null?void 0:_a.remarkPlugins)??[])},jsxOptions});if(sourceLoaderOptions)throw new Error(import_ts_dedent2.dedent`
|
|
29
|
+
Addon-docs no longer uses source-loader in 7.0.
|
|
30
|
+
|
|
31
|
+
To update your configuration, please see migration instructions here:
|
|
32
|
+
|
|
33
|
+
https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropped-source-loader--storiesof-static-snippets
|
|
34
|
+
`);if(mdxBabelOptions||configureJsx)throw new Error(import_ts_dedent2.dedent`
|
|
35
|
+
Addon-docs no longer uses configureJsx or mdxBabelOptions in 7.0.
|
|
36
|
+
|
|
37
|
+
To update your configuration, please see migration instructions here:
|
|
38
|
+
|
|
39
|
+
https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropped-addon-docs-manual-babel-configuration
|
|
40
|
+
`);let mdxVersion=(_b=import_global.global.FEATURES)!=null&&_b.legacyMdx1?"MDX1":"MDX2";import_node_logger2.logger.info(`Addon-docs: using ${mdxVersion}`);let mdxLoader=(_c=import_global.global.FEATURES)!=null&&_c.legacyMdx1?require.resolve("@storybook/mdx1-csf/loader"):require.resolve("@storybook/mdx2-csf/loader");return{...webpackConfig,plugins:[...webpackConfig.plugins||[],...csfPluginOptions?[(await import("@storybook/csf-plugin")).webpack(csfPluginOptions)]:[]],module:{...module2,rules:[...module2.rules,{test:/(stories|story)\.mdx$/,use:[{loader:mdxLoader,options:{...mdxLoaderOptions,skipCsf:!1}}]},{test:/\.mdx$/,exclude:/(stories|story)\.mdx$/,use:[{loader:mdxLoader,options:mdxLoaderOptions}]}]}}}var storyIndexers=indexers=>[{test:/(stories|story)\.mdx$/,indexer:async(fileName,opts)=>{var _a;let code=(await import_fs_extra.default.readFile(fileName,"utf-8")).toString(),{compile}=(_a=import_global.global.FEATURES)!=null&&_a.legacyMdx1?await import("@storybook/mdx1-csf"):await import("@storybook/mdx2-csf");return code=await compile(code,{}),(0,import_csf_tools.loadCsf)(code,{...opts,fileName}).parse()}},...indexers||[]],docs=docsOptions=>({...docsOptions,defaultName:"Docs",autodocs:"tag"}),addons=[require.resolve("@storybook/react-dom-shim/dist/preset")],webpackX=webpack,storyIndexersX=storyIndexers,docsX=docs;ensureReactPeerDeps();0&&(module.exports={addons,docs,storyIndexers,webpack});
|