Storybook: Docs view MDX addon

[ndelangen]

This is a list of stages we'll be working on

.1 ADD ability to render addon in main view based on route

• [x] extend lib/addon to have an API for adding other things then panels
• [x] extend components/preview to render full page panels and tabs to switch
• [ ] change panels to only show old/regular style addon panels
• [x] router

.2 ADD mdx addon that will render as full page

• [ ] render component.mdx
• [ ] Should be themable
• [ ] default should look github-like https://github.com/storybooks/storybook/issues/4339

.3 ADD option to reference story metadata

See https://github.com/storybooks/storybook/issues/4373

import { DocGen, PropsTable } from '@storybook/mdx';
import Component from './component';

# My component

## it's useful for ...

foo bar baz x

- x
- y
- z

<DocGen component={Component} />

<PropsTable component={Component} />

• [ ] Should extract metadata once per component/ref
• [ ] Should transform metadata to visual using a react component
• [ ] Component should be themable
• [ ] Should be able to extract typescript-types, flow-types, referenced proptypes https://github.com/storybooks/storybook/issues/3493 and HOC https://github.com/storybooks/storybook/issues/4016

.4 ADD option to reference a story

import { Example, Story } from '@storybook/mdx';
import Component from './component';

# My component

## it's useful for ...

foo bar baz x

- x
- y
- z

<Story id="UI-Layout-mobile" />

as a regex
<Story id={/UI-Layout-mobile/} />

as a array
<Story id=['UI-Layout-mobile']} />

• [ ] support for multiple iframes
• [ ] should load a story in an iframe
• [ ] auto-size of iframe

5. ADD option to embed code snippets

import { Example, Story } from '@storybook/mdx';
import Component from './component';

# My component

## it's useful for ...

foo bar baz x

- x
- y
- z

<Example>
  <Component>cool</Component>
</Example>

• [ ] Should be creating stories at build-time

.6 addon panels per iframe

• [ ] should be able to play with knobs per iframe/example

.7? examples.js file

// component.example.js

import React from 'react';

import Component from 'somewhere';

export default Component;

export const variant1 = () => <Component variant="1" />;
export const variant2 = () => <Component variant="2" />;
export const variant3 = () => <Component variant="3" />;

import { Example, Story } from '@storybook/mdx';
import Component from './component';
import * as examples from 'component.examples.js';

<Story file="./component.example.js" id="variant1" />

[tmeasday]

I've opened an issue discussing point (7) in more details, please take a look at the linked gist https://github.com/storybooks/storybook/issues/4848

[donaldpipowitch]

Thanks for the work so far! I'd like to showcase how we currently use MDX, just to give some feedback:

• We try to write a documentation page for every component in .mdx.
• This documentation can include several stand-alone examples (which don't use any Storybook API at all and are therefor very re-usable).
• We also load the source code of the examples, so it can be shown next to every example.
• -> To summarize: We have _n_ examples without any Storybook-specific code which we import into _one_ .mdx file which contains the documentation.

It looks like this:

import { Example } from '../../Example';
import Common from './Common';
import common from '!raw-loader!./Common';
import WithIcons from './WithIcons';
import withIcons from '!raw-loader!./WithIcons';

# Components

## Button

### Common usage

This is our normal `<Button/>`. You should use it in the following cases... (Some more documentation following an example which showcases this section...):

<Example source={common}><Common /></Example>

###  Usage with icons

You can add icons to your buttons in the following cases... (Some more documentation following an example which showcases this section...):

<Example source={withIcons}><WithIcons /></Example>

<Example/> is a component specifically written for our Storybook documentation. You could imagine some Fiddle-like widget embedded into the documentation, which shows our current example, but also offers a way to peek into the source code.

This is a little bit verbose, but does everything we want. It would be nice however to make this a little bit easier to use API-wise. 👍

And it would be nice if the MDX could be rendered with custom components.

[tmeasday]

Thanks for sharing @donaldpipowitch, that's a useful perspective

[JeroenReumkens]

Hey @ndelangen @tmeasday

Is this still being worked on? Anything I can help with?
I agree with previous people mentioning that this is what makes Docz stands out currently. I've already tried to make a mdx loader to convert mdx to stories, and use the mdx in Docz as well. That works, but it's quite hacky. My ideal situation would be using MDX for the stories, but also be able to generate just plain documentation inside Storybook (and show that in a nice way).

Thanks!

[shilman]

@JeroenReumkens Yeah now that SB5 is released and mostly stabilized, Storybook Docs is a main focus. We're doing some prototyping this week and will release something very soon for feedback. Since it's a major functional change we'll be releasing it in stages. If you want to participate, the best way is to join the #docs-mode channel on our Discord. I'll also be sharing on Github also for those who want to monitor what's going on.

[tomspeak]

We initially started with using our own (forcefully) inserted MDX with SB and it was too painful as in most cases you're forced to sit outside of the ecosystem, with a lot of integrations breaking.

This is not a complaint, we tried to go against the grain using something unsupported and it didn't work! This is just a heads up for anyone that was to preemptively jump on the MDX boat.

[shilman]

I'm closing this one. MDX has been available for awhile as part of addon-docs: https://github.com/storybookjs/storybook/blob/next/addons/docs/README.md

Most of the concerns raised in this issue are addressed, and those that aren't have individual issues.

MDX will be released as an experimental feature as part of 5.2! 🎉