Addon-docs: "Native"/natural MDX syntax

Umbrella issue to extend “native” MDX from React to other frameworks

Problem

Currently in @storybook/react you can write JSX directly in your MDX file:

<Story name='foo'><div className='bar'>baz</div></Story>

For @storybook/html you’d probably like to write the following, but it won’t work:

<Story name='foo'><div class='bar'>baz</div></Story>

Instead you’d have to write:

<Story name='foo'>{`<div class='bar'>baz</div>`}</Story>

Here’s what’s going on:

1. The MDX is getting parsed by the @mdx-js/mdx parser
2. The resulting JSX is getting processed by our mdx-compiler-plugin
3. The output of the plug in CSF
4. CSF is getting loaded into the storiesOf API

The contents of the <Story> element is isomorphic to the return value of the CSF function, which is equal to the storiesOf storyFn.

Solution

For an alternative syntax to work, there are a bunch of things that need to happen:

1. We need to determine the desired syntax
2. Can it be parsed by the MDX parser?
3. Can it be transformed into the format required by the storiesOf API (the return value of storyFn for that particular framework)
4. Is that the currently storiesOf format we want to support in the future? I.e. if CSF is meant to become an open standard, we probably might to give that more thought to that. E.g. https://github.com/storybookjs/storybook/pull/7682 rethinks that for Svelte

Frameworks

We can do this framework by framework. Here are the ones that are on my radar right now. Can add more later.

• React
• Vue
• Angular
• HTML
• Svelte
• StencilJS

[0gust1]

For information, on Svelte side, the equivalent of MDX is https://github.com/pngwn/MDsveX I did some extensive tests, it’s handled pretty well by the Svelte compiler (as a preprocess step that is feeded on the compiler). On Storybook side, I still have to catch up on the corresponding MRs.

[shilman]

Here’s a comment from a slack user, kind of contradicting what I said above:

On a random side note, interestingly with this mdx format I’ve been able to drop storybook/html and use storybook/react for my web components, the behavior of this works much nicer as the JSX support makes it easy to render the web components, can’t see any downsides thus far.

Here’s a snippet:

import '.';
import '../icon';
import { Meta, Story, Preview, html, text, boolean } from '[redacted]';
import ReadMe from './README.md';

<Meta title="UI Kit|Accordion" />

<!-- Workaround until transclusion of md files is supported outright -->
<ReadMe.parameters.docs.page />

## Stories

<Preview>
    <Story name="default">
        <magic-ui-accordion>
            <b slot="toggle">{text('Toggle Text', 'Default Toggle Text')}</b>
            <ul slot="content">
                <p>This is some content to display!</p>
                <p>It's toggled every time the page is toggled</p>
            </ul>
        </magic-ui-accordion>
    </Story>
</Preview>