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