mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 07:21:16 +08:00
Addon-docs: Packaging for 5.2 release (#7741)
Addon-docs: Packaging for 5.2 release
This commit is contained in:
Michael Shilman
GitHub
commit
83dc23fd0e
@ -1,29 +1,92 @@
|
||||
<center>
|
||||
<img src="docs/media/hero.png" width="100%" />
|
||||
</center>
|
||||
|
||||
# Storybook Docs
|
||||
|
||||
Living documentation for your components.
|
||||
Storybook Docs transforms your Storybook stories into world-class component documentation.
|
||||
|
||||
- [Sneak peak article](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
|
||||
- [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)
|
||||
**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 simple, easy-to-read pages.
|
||||
|
||||
## View layer support
|
||||
**MDX.** If you want more control, `MDX` allows you to write long-form markdown documentation and stories in one file. You can also use it to write pure documentation pages and embed them inside your Storybook alongside your stories.
|
||||
|
||||
Docs supports all view layers that Storybook supports except for React Native (currently). There are some view-layer specific
|
||||
Just like Storybook, Docs supports every major view layer including React, Vue, Angular, HTML, Web components, Svelte, and many more.
|
||||
|
||||
Read on to learn more:
|
||||
|
||||
- [DocsPage](#docspage)
|
||||
- [MDX](#mdx)
|
||||
- [Framework support](#framework-support)
|
||||
- [Installation](#installation)
|
||||
- [Preset options](#preset-options)
|
||||
- [Manual configuration](#manual-configuration)
|
||||
- [More resources](#more-resources)
|
||||
|
||||
## DocsPage
|
||||
|
||||
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.
|
||||
|
||||
Click on the `Docs` tab to see it:
|
||||
|
||||
<center>
|
||||
<img src="docs/media/docs-tab.png" width="100%" />
|
||||
</center>
|
||||
|
||||
For more information on how it works, see the [`DocsPage` reference](./docs/docspage.md).
|
||||
|
||||
## MDX
|
||||
|
||||
`MDX` is a syntax for writing long-form documentation and 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.
|
||||
|
||||
Here's an example file:
|
||||
|
||||
```md
|
||||
import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
|
||||
import { Checkbox } from './Checkbox';
|
||||
|
||||
<Meta title="MDX|Checkbox" component={Checkbox} />
|
||||
|
||||
# Checkbox
|
||||
|
||||
With `MDX` we can define a story for `Checkbox` right in the middle of our
|
||||
markdown documentation.
|
||||
|
||||
<Preview>
|
||||
<Story name="all checkboxes">
|
||||
<form>
|
||||
<Checkbox id="Unchecked" label="Unchecked" />
|
||||
<Checkbox id="Checked" label="Checked" checked />
|
||||
<Checkbox appearance="secondary" id="second" label="Secondary" checked />
|
||||
</form>
|
||||
</Story>
|
||||
</Preview>
|
||||
```
|
||||
|
||||
And here's how that's rendered in Storybook:
|
||||
|
||||
<center>
|
||||
<img src="docs/media/mdx-simple.png" width="100%" />
|
||||
</center>
|
||||
|
||||
For more information on `MDX`, see the [`MDX` reference](./docs/mdx.md).
|
||||
|
||||
## Framework support
|
||||
|
||||
Storybook Docs supports all view layers that Storybook supports except for React Native (currently). There are some view-layer specific
|
||||
features as well. This chart captures the current state of support
|
||||
|
||||
| | React | Vue | Angular | Polymer | Mithril | HTML | Marko | Svelte | Riot | Ember | Preact |
|
||||
| -------------- | :---: | :-: | :-----: | :-----: | :-----: | :--: | :---: | :----: | :--: | :---: | :----: |
|
||||
| | React | Vue | Angular | HTML | Svelte | Polymer | Marko | Mithril | Riot | Ember | Preact |
|
||||
| ----------------- | :---: | :-: | :-----: | :--: | :----: | :-----: | :---: | :-----: | :--: | :---: | :----: |
|
||||
| MDX stories | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| Module stories | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| Legacy stories | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| CSF stories | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| StoriesOf stories | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| Source | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| Notes / Info | + | + | + | + | + | + | + | + | + | + | + |
|
||||
| Props table | + | + | # | | | | | | | | |
|
||||
| Docgen | + | + | # | | | | | | | | |
|
||||
| Inline stories | + | # | | | | | | | | | |
|
||||
|
||||
**Notes:**
|
||||
|
||||
- `#` denotes planned/WIP support
|
||||
**Note:** `#` = WIP support
|
||||
|
||||
## Installation
|
||||
|
||||
@ -33,7 +96,13 @@ First add the package. Make sure that the versions for your `@storybook/*` packa
|
||||
yarn add -D @storybook/addon-docs
|
||||
```
|
||||
|
||||
The add the following to your `.storybook/presets.js` exports:
|
||||
Docs has peer dependencies on `react` and `babel-loader`. If you want to write stories in MDX, you may need to add these dependencies as well:
|
||||
|
||||
```sh
|
||||
yarn add -D react babel-loader
|
||||
```
|
||||
|
||||
Then add the following to your `.storybook/presets.js` exports:
|
||||
|
||||
```js
|
||||
module.exports = ['@storybook/addon-docs/react/preset'];
|
||||
@ -41,6 +110,16 @@ module.exports = ['@storybook/addon-docs/react/preset'];
|
||||
|
||||
If you're not using `react`, replace it with your framework of choice corresponding to the Storybook package name, e.g. `angular` for `@storybook/angular` etc.
|
||||
|
||||
If you're migrating from an earlier version of Storybook and want to use `MDX`, you need to upgrade your Storybook config:
|
||||
|
||||
```js
|
||||
import { configure } from '@storybook/react';
|
||||
|
||||
configure(require.context('../src', true, /\.stories\.(js|mdx)$/), module);
|
||||
```
|
||||
|
||||
For more information on the new `configure`, see ["Loading stories"](https://github.com/storybookjs/storybook/blob/next/docs/src/pages/basics/writing-stories/index.md#loading-stories) in the Storybook documentation.
|
||||
|
||||
## Preset options
|
||||
|
||||
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:
|
||||
@ -101,3 +180,10 @@ module.exports = async ({ config }) => {
|
||||
return config;
|
||||
};
|
||||
```
|
||||
|
||||
## More resources
|
||||
|
||||
Want to learn more? Here are some more articles on Storybook Docs:
|
||||
|
||||
- [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
|
||||
- [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)
|
||||
|
||||
198
addons/docs/docs/docspage.md
Normal file
198
addons/docs/docs/docspage.md
Normal file
@ -0,0 +1,198 @@
|
||||
<center>
|
||||
<img src="./media/docspage-hero.png" width="100%" />
|
||||
</center>
|
||||
|
||||
# Storybook DocsPage
|
||||
|
||||
When you install [Storybook Docs](../README.md), `DocsPage` is the zero-config default documentation that all stories get out of the box. It aggregates your stories, text descriptions, docgen comments, props tables, and code examples into a single page for each component.
|
||||
|
||||
- [Motivation](#motivation)
|
||||
- [Component parameter](#component-parameter)
|
||||
- [DocsPage slots](#docspage-slots)
|
||||
- [More resources](#more-resources)
|
||||
|
||||
## Motivation
|
||||
|
||||
`DocsPage` is the successor to [`addon-info`](https://github.com/storybookjs/storybook/tree/next/addons/info), which was one of the most popular Storybook addons despite many limitations.
|
||||
|
||||
Like `addon-info`, `DocsPage` provides sensible defaults, meaning it adds documentation to your existing Storybook without requiring any additional work on your part.
|
||||
|
||||
However, `DocsPage` brings the following improvements:
|
||||
|
||||
- It supports all frameworks that Storybook supports, including React, Vue, Angular and [many others](../README.md#framework-support).
|
||||
- It generates better documentation that can be used as a standalone docs site, independently of Storybook.
|
||||
- It supports better configuration, so you can capture project specific information with ease.
|
||||
- It's built to work with [`MDX`](./mdx.md`) when you need more control of your documentation.
|
||||
|
||||
## Component parameter
|
||||
|
||||
`DocsPage` pulls info from many sources, but one of the main ones is the `component` parameter, which is a new addition to Storybook in 5.2. It's based on the best practice that each component should have an associated set of documentation and stories (versus organizing it in some other way).
|
||||
|
||||
Storybook uses `component` to extract the component's description and props, and will rely on it further in future releases. We encourage you to add it to existing stories and use it in all new stories.
|
||||
|
||||
Here's how to set the component in [Component Story Format (CSF)]():
|
||||
|
||||
```js
|
||||
import { Badge } from './Badge';
|
||||
|
||||
export default {
|
||||
title: 'Path/to/Badge',
|
||||
component: Badge,
|
||||
};
|
||||
```
|
||||
|
||||
And here's how to do the same thing the underlying `storiesOf` API:
|
||||
|
||||
```js
|
||||
import { storiesOf } from '@storybook/react';
|
||||
import { Badge } from './Badge';
|
||||
|
||||
storiesOf('Path/to/Badge', module).addParameters({ component: Badge });
|
||||
```
|
||||
|
||||
If you're coming from the`storiesOf` format, there's [a codemod that adds it for you](https://github.com/storybookjs/storybook/blob/next/lib/codemod/README.md#add-component-parameters).
|
||||
|
||||
## DocsPage slots
|
||||
|
||||
`DocsPage` is organized into a series of "slots" including Title, Subtitle, Description, Props, and Story. Each of these slots pulls information from your project and formats it for the screen.
|
||||
|
||||
<center>
|
||||
<img style="padding: 30px; border: 3px solid #eee;" src="./media/docspage-slots.png" width="100%" />
|
||||
</center>
|
||||
|
||||
## Slot values
|
||||
|
||||
Each of the slots is computed by a built-in function, that can also be overridden using [Slot Function](#slot-functions).
|
||||
|
||||
Here is a summary of the slots, where the data comes from by default, and the slot function that can be used to override it:
|
||||
|
||||
| Slot | Default source | Slot function | Frameworks |
|
||||
| ----------- | ----------------------------------- | ----------------- | ---------- |
|
||||
| Title | component `title` | `titleSlot` | All |
|
||||
| Subtitle | `componentSubtitle` parameter | `subtitleSlot` | All |
|
||||
| Description | component `docgen` comment | `descriptionSlot` | React, Vue |
|
||||
| Primary | storybook stories | `primarySlot` | All |
|
||||
| Props | component docgen props or propTypes | `propsSlot` | React, Vue |
|
||||
| Stories | storybook stories | `storiesSlot` | All |
|
||||
|
||||
For more information on frameworks, see ["Framework support"](../README.md#framework-support)
|
||||
|
||||
### Title
|
||||
|
||||
`Title` is computed from the component's `title`, and matches the component caption in Storybook's navigation.
|
||||
|
||||
For example:
|
||||
|
||||
```js
|
||||
export default {
|
||||
title: 'Path/to/Badge',
|
||||
};
|
||||
```
|
||||
|
||||
### Subtitle
|
||||
|
||||
The `Subtitle` slot is computed from the component's `componentSubtitle` parameter.
|
||||
|
||||
For example in [Component Story Format (CSF)](https://medium.com/storybookjs/component-story-format-66f4c32366df):
|
||||
|
||||
```js
|
||||
export default {
|
||||
...
|
||||
parameters: {
|
||||
componentSubtitle: 'Handy status label',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Description
|
||||
|
||||
The `Description` slot is computed from the Component's docgen comments in the component's source.
|
||||
|
||||
For example, here's the source for `Badge`:
|
||||
|
||||
```js
|
||||
/**
|
||||
* Use `Badge` to highlight key info with a predefined status. Easy peasy!
|
||||
*/
|
||||
export const Badge = ({ status, children }) => { ... }
|
||||
```
|
||||
|
||||
### Primary
|
||||
|
||||
The `Primary` slot is computed from the first user-defined story for the component.
|
||||
|
||||
For example here are `Badge`'s stories in CSF. The `allBadges` is selected as the primary story because it's first:
|
||||
|
||||
```js
|
||||
// export default { ... }; /* Badge component metadata */
|
||||
export const allBadges = () => ...
|
||||
export const positive = () => ...
|
||||
export const negative = () => ...
|
||||
```
|
||||
|
||||
### Props
|
||||
|
||||
The `Props` slot is computed from the component's docgen props, which can be defined in typescript or using `react` PropTypes.
|
||||
|
||||
For example, here are the `PropTypes` for the `Badge` component
|
||||
|
||||
```js
|
||||
import PropTypes from 'prop-types';
|
||||
|
||||
// ... Badge definition ...
|
||||
|
||||
Badge.propTypes = {
|
||||
status: PropTypes.oneOf(['positive', 'negative', 'neutral', 'error', 'warning']),
|
||||
};
|
||||
Badge.defaultProps = {
|
||||
status: 'neutral',
|
||||
};
|
||||
```
|
||||
|
||||
### Stories
|
||||
|
||||
The `Stories` slot is computed from the user-defined stories for the component, excluding the first.
|
||||
|
||||
For example here are `Badge`'s stories in CSF. The `positive` and `negative` stories are selected in that order:
|
||||
|
||||
```js
|
||||
// export default { ... }; /* Badge component metadata */
|
||||
export const allBadges = () => ...
|
||||
export const positive = () => ...
|
||||
export const negative = () => ...
|
||||
```
|
||||
|
||||
## Slot functions
|
||||
|
||||
> ⚠️ Slot functions are an experimental feature in Storybook 5.2. The API may change in 5.3 outside of the normal semver rules. Be forewarned!
|
||||
|
||||
The value for each slot is computed from a `SlotContext` context, and the function that's used to compute the value can be overridden if you need to customize the page. If you find yourself doing a lot of configuration, or wanting different configurations for different pages, you might be better off using `MDX`. Everything that `DocsPage` gives you can be reconstructed in a few lines of `MDX`.
|
||||
|
||||
Here is the `SlotContext` type definition:
|
||||
|
||||
```ts
|
||||
export interface SlotContext {
|
||||
id?: string;
|
||||
selectedKind?: string;
|
||||
selectedStory?: string;
|
||||
parameters?: any;
|
||||
storyStore?: any;
|
||||
}
|
||||
```
|
||||
|
||||
And here are the return type signatures for each of the slot functions
|
||||
|
||||
| Slot | Function | Inputs | Output |
|
||||
| -------- | ------------ | ---------------------------- | ------------------ |
|
||||
| Title | titleSlot | `SlotContext` | `string?` |
|
||||
| Subtitle | subtitleSlot | `SlotContext` | `string?` |
|
||||
| Primary | primarySlot | `StoryData[]`, `SlotContext` | `StoryProps?` |
|
||||
| Props | propsSlot | `SlotContext` | `PropsTableProps?` |
|
||||
| Stories | storiesSlot | `StoryData[]`, `SlotContext` | `StoryProps[]?` |
|
||||
|
||||
## More resources
|
||||
|
||||
Want to learn more? Here are some more articles on Storybook Docs:
|
||||
|
||||
- [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
|
||||
- [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)
|
||||
187
addons/docs/docs/mdx.md
Normal file
187
addons/docs/docs/mdx.md
Normal file
@ -0,0 +1,187 @@
|
||||
<center>
|
||||
<img src="./media/mdx-hero.png" width="100%" />
|
||||
</center>
|
||||
|
||||
# Storybook Docs MDX
|
||||
|
||||
> ⚠️ MDX support is an experimental feature in Storybook 5.2. The API may change in 5.3 outside of the normal semver rules. Be forewarned!
|
||||
|
||||
`MDX` is the syntax [Storybook Docs](../README.md) uses to capture long-form markdown documentation and stories in one file. You can also write pure documentation pages in `MDX` and add them to Storybook alongside your stories.
|
||||
|
||||
- [Basic example](#basic-example)
|
||||
- [MDX-Flavored CSF](#mdx-flavored-csf)
|
||||
- [Writing stories](#writing-stories)
|
||||
- [Embedding stories](#embedding-stories)
|
||||
- [Decorators and parameters](#decorators-and-parameters)
|
||||
- [MDX file names](#mdx-file-names)
|
||||
- [More resources](#more-resources)
|
||||
|
||||
## Basic example
|
||||
|
||||
Let's get started with a simple example that combines markdown with a single story:
|
||||
|
||||
```md
|
||||
import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
|
||||
import { Checkbox } from './Checkbox';
|
||||
|
||||
<Meta title="MDX|Checkbox" component={Checkbox} />
|
||||
|
||||
# Checkbox
|
||||
|
||||
With `MDX` we can define a story for `Checkbox` right in the middle of our
|
||||
markdown documentation.
|
||||
|
||||
<Preview>
|
||||
<Story name="all checkboxes">
|
||||
<form>
|
||||
<Checkbox id="Unchecked" label="Unchecked" />
|
||||
<Checkbox id="Checked" label="Checked" checked />
|
||||
<Checkbox appearance="secondary" id="second" label="Secondary" checked />
|
||||
</form>
|
||||
</Story>
|
||||
</Preview>
|
||||
```
|
||||
|
||||
And here's how that's rendered in Storybook:
|
||||
|
||||
<center>
|
||||
<img src="./media/mdx-simple.png" width="100%" />
|
||||
</center>
|
||||
|
||||
As you can see there's a lot going on here. We're writing Markdown, we're writing JSX, and somehow we're also defining Storybook stories that are drop-in compatible with the entire Storybook ecosystem.
|
||||
|
||||
Let's break it down.
|
||||
|
||||
## MDX-Flavored CSF
|
||||
|
||||
[MDX](https://mdxjs.com/) is a standard file format that combines Markdown with JSX. This means you can use Markdown’s terse syntax (such as `# heading`) for your documentation, and freely embed JSX component blocks at any point in the file.
|
||||
|
||||
MDX-flavored [Component Story Format (CSF)](https://medium.com/storybookjs/component-story-format-66f4c32366df) includes a collection of components called **"Doc Blocks"**, that allow Storybook to translate MDX files into storybook stories. MDX-defined stories are identical to regular Storybook stories, so they can be used with Storybook's entire ecosystem of addons and view layers.
|
||||
|
||||
For example, here's the story from `Checkbox` example above, rewritten in CSF:
|
||||
|
||||
```js
|
||||
import React from 'react';
|
||||
import { Checkbox } from './Checkbox';
|
||||
export default { title: "MDX|Checkbox" component: Checkbox };
|
||||
export const allCheckboxes = () => (
|
||||
<form>
|
||||
<Checkbox id="Unchecked" label="Unchecked" />
|
||||
<Checkbox id="Checked" label="Checked" checked />
|
||||
<Checkbox appearance="secondary" id="second" label="Secondary" checked />
|
||||
</form>
|
||||
);
|
||||
```
|
||||
|
||||
There's a one-to-one mapping from the code in `MDX` to `CSF`, which in turn directly corresponds to Storybook's internal `storiesOf` API. As a user this means your existing Storybook knowledge should easily translate between the three. And technically, this means that the transformations that happen under the hood are simple and predictable.
|
||||
|
||||
## Writing stories
|
||||
|
||||
Now let's look at a more realistic example to see a few more things we can do:
|
||||
|
||||
```md
|
||||
import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
|
||||
|
||||
import { Badge } from './Badge';
|
||||
import { Icon } from './Icon';
|
||||
|
||||
<Meta title="MDX|Badge" component={Badge} />
|
||||
|
||||
# Badge
|
||||
|
||||
Let's define a story for our `Badge` component:
|
||||
|
||||
<Story name="positive">
|
||||
<Badge status="positive">Positive</Badge>
|
||||
</Story>
|
||||
|
||||
We can drop it in a `Preview` to get a code snippet:
|
||||
|
||||
<Preview>
|
||||
<Story name="negative">
|
||||
<Badge status="negative">Negative</Badge>
|
||||
</Story>
|
||||
</Preview>
|
||||
|
||||
We can even preview multiple stories in a block. This
|
||||
gets rendered as a group, but defines individual stories
|
||||
with unique URLs and isolated snapshot tests.
|
||||
|
||||
<Preview>
|
||||
<Story name="warning">
|
||||
<Badge status="warning">Warning</Badge>
|
||||
</Story>
|
||||
<Story name="neutral">
|
||||
<Badge status="neutral">Neutral</Badge>
|
||||
</Story>
|
||||
<Story name="error">
|
||||
<Badge status="error">Error</Badge>
|
||||
</Story>
|
||||
<Story name="with icon">
|
||||
<Badge status="warning">
|
||||
<Icon icon="check" inline />
|
||||
with icon
|
||||
</Badge>
|
||||
</Story>
|
||||
</Preview>
|
||||
```
|
||||
|
||||
And here's how that gets rendered in Storybook:
|
||||
|
||||
<center>
|
||||
<img src="./media/mdx-page.png" width="100%" />
|
||||
</center>
|
||||
|
||||
## Embedding stories
|
||||
|
||||
Suppose you have an existing story and want to embed it into your docs. Here's how to show a story with ID `some--id` (check the browser URL in Storybook v5+ to see a story's ID):
|
||||
|
||||
```md
|
||||
import { Story } from "@storybook/addon-docs/blocks";
|
||||
|
||||
# Some header
|
||||
|
||||
And markdown here
|
||||
|
||||
<Story id="some--id" />
|
||||
```
|
||||
|
||||
You can also use the rest of the MDX features in conjunction with embedding. That includes source, preview, and prop tables.
|
||||
|
||||
## Decorators and parameters
|
||||
|
||||
To add [decorators](https://github.com/storybookjs/storybook/blob/next/docs/src/pages/basics/writing-stories/index.md#decorators) and [parameters](https://github.com/storybookjs/storybook/blob/next/docs/src/pages/basics/writing-stories/index.md#parameters) in MDX:
|
||||
|
||||
```md
|
||||
<Meta
|
||||
title='MyComponent'
|
||||
decorators={[ ... ]}
|
||||
parameters={{ ... }}
|
||||
/>
|
||||
|
||||
<Story name="story" decorators={[ ... ]} parameters={{ ... }} >
|
||||
...
|
||||
</Story>
|
||||
```
|
||||
|
||||
In addition, global decorators work just like before, e.g. adding the following to your `.storybook/config.js`:
|
||||
|
||||
```js
|
||||
import { addDecorator, addParameters } from '@storybook/react';
|
||||
|
||||
addDecorator(...);
|
||||
addParameters({ ... });
|
||||
```
|
||||
|
||||
## MDX file names
|
||||
|
||||
Unless you use a custom webpack configuration, all of your `MDX` files should have the suffix `*.stories.mdx`. This tells Storybook to apply its special processing to the `<Meta>` and `<Story>` elements in the file.
|
||||
|
||||
Be sure to update your Storybook config file to load `.stories.mdx` stories, as per the [`addon-docs` installation instructions](../README.md#installation).
|
||||
|
||||
## More resources
|
||||
|
||||
`MDX` is an experimental feature and there's a lot more that hasn't been documented yet. Here are some more articles on Storybook Docs that contain more information:
|
||||
|
||||
- [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
|
||||
- [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)
|
||||
BIN
addons/docs/docs/media/docs-tab.png
Normal file
BIN
addons/docs/docs/media/docs-tab.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 157 KiB |
BIN
addons/docs/docs/media/docspage-hero.png
Normal file
BIN
addons/docs/docs/media/docspage-hero.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 422 KiB |
BIN
addons/docs/docs/media/docspage-slots.png
Normal file
BIN
addons/docs/docs/media/docspage-slots.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 153 KiB |
BIN
addons/docs/docs/media/hero.png
Normal file
BIN
addons/docs/docs/media/hero.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 832 KiB |
BIN
addons/docs/docs/media/mdx-hero.png
Normal file
BIN
addons/docs/docs/media/mdx-hero.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
BIN
addons/docs/docs/media/mdx-page.png
Normal file
BIN
addons/docs/docs/media/mdx-page.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 190 KiB |
BIN
addons/docs/docs/media/mdx-simple.png
Normal file
BIN
addons/docs/docs/media/mdx-simple.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
@ -25,6 +25,7 @@
|
||||
"dependencies": {
|
||||
"@babel/generator": "^7.4.0",
|
||||
"@babel/parser": "^7.4.2",
|
||||
"@babel/plugin-transform-react-jsx": "^7.3.0",
|
||||
"@mdx-js/loader": "^1.1.0",
|
||||
"@mdx-js/mdx": "^1.1.0",
|
||||
"@mdx-js/react": "^1.0.27",
|
||||
@ -46,7 +47,8 @@
|
||||
"@types/webpack-env": "^1.13.7"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"react": "*"
|
||||
"react": "^16.8.0",
|
||||
"babel-loader": "^8.0.0"
|
||||
},
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
|
||||
@ -13,22 +13,28 @@ import { DocsContainer } from './DocsContainer';
|
||||
import { Description, getDocgen } from './Description';
|
||||
import { Story } from './Story';
|
||||
import { Preview } from './Preview';
|
||||
import { Props, getPropsTableProps } from './Props';
|
||||
import { getPropsTableProps } from './Props';
|
||||
|
||||
export type StringSlot = (context: DocsContextProps) => string | void;
|
||||
export type PropsSlot = (context: DocsContextProps) => PropsTableProps | void;
|
||||
export type StorySlot = (
|
||||
storyData: StoryData,
|
||||
isPrimary: boolean,
|
||||
context: DocsContextProps
|
||||
) => DocsStoryProps;
|
||||
export interface SlotContext {
|
||||
id?: string;
|
||||
selectedKind?: string;
|
||||
selectedStory?: string;
|
||||
parameters?: any;
|
||||
storyStore?: any;
|
||||
}
|
||||
|
||||
export type StringSlot = (context: SlotContext) => string | void;
|
||||
export type PropsSlot = (context: SlotContext) => PropsTableProps | void;
|
||||
export type StorySlot = (stories: StoryData[], context: SlotContext) => DocsStoryProps | void;
|
||||
export type StoriesSlot = (stories: StoryData[], context: SlotContext) => DocsStoryProps[] | void;
|
||||
|
||||
export interface DocsPageProps {
|
||||
titleSlot: StringSlot;
|
||||
subtitleSlot: StringSlot;
|
||||
descriptionSlot: StringSlot;
|
||||
primarySlot: StorySlot;
|
||||
propsSlot: PropsSlot;
|
||||
storySlot: StorySlot;
|
||||
storiesSlot: StoriesSlot;
|
||||
}
|
||||
|
||||
interface DocsStoryProps {
|
||||
@ -58,14 +64,21 @@ const defaultTitleSlot: StringSlot = ({ selectedKind, parameters }) => {
|
||||
};
|
||||
|
||||
const defaultSubtitleSlot: StringSlot = ({ parameters }) =>
|
||||
parameters && parameters.componentDescription;
|
||||
parameters && parameters.componentSubtitle;
|
||||
|
||||
const defaultPropsSlot: PropsSlot = context => getPropsTableProps({ of: '.' }, context);
|
||||
|
||||
const defaultDescriptionSlot: StringSlot = ({ parameters }) =>
|
||||
parameters && getDocgen(parameters.component);
|
||||
|
||||
const defaultStorySlot: StorySlot = (storyData, isPrimary, context) => storyData;
|
||||
const defaultPrimarySlot: StorySlot = stories => stories && stories[0];
|
||||
const defaultStoriesSlot: StoriesSlot = stories => {
|
||||
if (stories && stories.length > 1) {
|
||||
const [first, ...rest] = stories;
|
||||
return rest;
|
||||
}
|
||||
return null;
|
||||
};
|
||||
|
||||
const StoriesHeading = styled.h2();
|
||||
const StoryHeading = styled.h3();
|
||||
@ -89,8 +102,9 @@ const DocsPage: React.FunctionComponent<DocsPageProps> = ({
|
||||
titleSlot,
|
||||
subtitleSlot,
|
||||
descriptionSlot,
|
||||
primarySlot,
|
||||
propsSlot,
|
||||
storySlot,
|
||||
storiesSlot,
|
||||
}) => (
|
||||
<DocsContext.Consumer>
|
||||
{context => {
|
||||
@ -103,17 +117,16 @@ const DocsPage: React.FunctionComponent<DocsPageProps> = ({
|
||||
const componentStories = (storyStore.raw() as StoryData[]).filter(
|
||||
s => s.kind === selectedKind
|
||||
);
|
||||
const [primary, ...rest] = componentStories.map((storyData, idx) =>
|
||||
storySlot(storyData, idx === 0, context)
|
||||
);
|
||||
const primary = primarySlot(componentStories, context);
|
||||
const stories = storiesSlot(componentStories, context);
|
||||
|
||||
return (
|
||||
<PureDocsPage title={title} subtitle={subtitle}>
|
||||
<Description markdown={description} />
|
||||
<DocsStory {...primary} expanded={false} />
|
||||
{primary && <DocsStory {...primary} expanded={false} />}
|
||||
{propsTableProps && <PropsTable {...propsTableProps} />}
|
||||
<StoriesHeading>Stories</StoriesHeading>
|
||||
{rest.map(story => story && <DocsStory {...story} expanded />)}
|
||||
{stories && stories.map(story => story && <DocsStory {...story} expanded />)}
|
||||
</PureDocsPage>
|
||||
);
|
||||
}}
|
||||
@ -125,8 +138,9 @@ interface DocsPageWrapperProps {
|
||||
titleSlot?: StringSlot;
|
||||
subtitleSlot?: StringSlot;
|
||||
descriptionSlot?: StringSlot;
|
||||
primarySlot?: StorySlot;
|
||||
propsSlot?: PropsSlot;
|
||||
storySlot?: StorySlot;
|
||||
storiesSlot?: StoriesSlot;
|
||||
}
|
||||
|
||||
const DocsPageWrapper: React.FunctionComponent<DocsPageWrapperProps> = ({
|
||||
@ -134,14 +148,17 @@ const DocsPageWrapper: React.FunctionComponent<DocsPageWrapperProps> = ({
|
||||
titleSlot = defaultTitleSlot,
|
||||
subtitleSlot = defaultSubtitleSlot,
|
||||
descriptionSlot = defaultDescriptionSlot,
|
||||
primarySlot = defaultPrimarySlot,
|
||||
propsSlot = defaultPropsSlot,
|
||||
storySlot = defaultStorySlot,
|
||||
storiesSlot = defaultStoriesSlot,
|
||||
}) => (
|
||||
/* eslint-disable react/destructuring-assignment */
|
||||
<DocsContainer
|
||||
context={{ ...context, mdxKind: context.selectedKind }}
|
||||
content={() => (
|
||||
<DocsPage {...{ titleSlot, subtitleSlot, descriptionSlot, storySlot, propsSlot }} />
|
||||
<DocsPage
|
||||
{...{ titleSlot, subtitleSlot, descriptionSlot, primarySlot, propsSlot, storiesSlot }}
|
||||
/>
|
||||
)}
|
||||
/>
|
||||
);
|
||||
|
||||
@ -198,7 +198,7 @@ addParameters({ notes: defaultNotes });
|
||||
|
||||
This would make sense if, for example, `instructions.md` contained instructions on how to document your components when there is no documentation available.
|
||||
|
||||
Then for componenents that did have documentation, we might override it at the component/story level:
|
||||
Then for components that did have documentation, we might override it at the component/story level:
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
@ -219,7 +219,7 @@ special.story = {
|
||||
};
|
||||
```
|
||||
|
||||
In this example, the `small` and `medium` stories get the compoonent notes documented in `notes.md` (as opposed to the generic instructions in `instructions.md`). The `special` story gets some special notes.
|
||||
In this example, the `small` and `medium` stories get the component notes documented in `notes.md` (as opposed to the generic instructions in `instructions.md`). The `special` story gets some special notes.
|
||||
|
||||
## Searching
|
||||
|
||||
|
||||
27
lib/ui/src/components/sidebar/Sidebar.stories.mdx
Normal file
27
lib/ui/src/components/sidebar/Sidebar.stories.mdx
Normal file
@ -0,0 +1,27 @@
|
||||
import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
|
||||
|
||||
import Sidebar from './Sidebar';
|
||||
import { standardData } from './SidebarHeading.stories';
|
||||
import { withRootData } from './SidebarStories.stories';
|
||||
|
||||
<Meta component="Sidebar" title="Addons|Docs/Sidebar" />
|
||||
|
||||
# Sidebar
|
||||
|
||||
Here's some custom documentation for Storybook's `Sidebar` component.
|
||||
|
||||
<Preview>
|
||||
<Story name="simple" height="150px">
|
||||
<Sidebar
|
||||
menu={standardData.menu}
|
||||
stories={withRootData.stories}
|
||||
storyId={withRootData.storyId}
|
||||
/>
|
||||
</Story>
|
||||
</Preview>
|
||||
|
||||
<Preview>
|
||||
<Story name="loading" height="150px">
|
||||
<Sidebar menu={standardData.menu} stories={{}} loading />
|
||||
</Story>
|
||||
</Preview>
|
||||
Loading…
x
Reference in New Issue
Block a user