Storybook Docs Migration

docs-migration.md

Storybook Docs: Migration

So you’re excited about Storybook Docs but you’re building your design system in Storybook RIGHT NOW. What should you do?

This guide shows you how Storybook Docs tells you how we’re going to incorporate information from addon-notes and addon-info and to make the transition easy.

TIP: if you’re starting today, we recommend using addon-notes.

DISCLAIMER: This is speculative and the details are likely to change before the release. It's also open for feedback--please comment below or DM me in Discord if you see opportunities for improvement.

Text/markdown from addon-notes

Addon-notes takes a string or object as its argument:

storiesOf(…).add('story1', () => <Component />, { notes: 'some info' });
storiesOf(…).add('story2', () => <Component />, { notes: { text: 'some other info' });
storiesOf(…).add('story3', () => <Component />, { notes: { markdown: 'some other info' });

Text from addon-info

Addon-info takes a text string or an object as its argument.

storiesOf(…).add('story4', () => <Component />, { info: 'some info' });
storiesOf(…).add('story5', () => <Component />, { info: { text: 'some other info' });

addon-info takes many other arguments to control the display of source code, prop tables, and so forth. Migrating that information will be covered separately.

Migration

Given that both addon-notes and addon-info provide a way to annotate a component / story with a text/markdown string, we’ll make it easy to re-use this annotation in Storybook Docs through the use of Doc Blocks.

Here’s how that will work in your MDX:

import { Notes } from ‘@storybook/docs’;

# Some header

<Notes id="some--id" />

This will inline the notes from the story “some—id” into your markdown. And if you want to parameterize your MDX so it always displays the notes from the currently visible story, you can simply omit the “id” prop:

import { Notes } from ‘@storybook/docs’;

# Some header

<Notes />

We'll probably do something similar with <Info />, or maybe <Notes param="info" />, details TBD.