addon-docs with regular markdown

Describe the solution you’d like .mdx is a pretty cool format, but it may not play well with every type of framework and requires a transformation step. It would be cool if the docs addon could work with regular markdown and html as well.

Because markdown can render HTML elements, you can use that to embed stories and cover at least the basic use cases.

It could look something like this:

example.stories.md

# Title

## Subtitle 1

Paragraph 1

<docs-story name="storyA"></docs-story>

## Subtitle

Paragraph 2

<docs-story name="storyB"></docs-story>

example.stories.js

import React from 'react';
import { action } from '@storybook/addon-actions';
import { fromMarkdown } from '@storybook/addon-docs';
import { Button } from '@storybook/react/demo';

export default {
  title: 'Button',
  parameters: {
    component: Button,
    docs: {
      page: fromMarkdown('./example.stories.md'),
    }
  },
};

export const Story1 = () => <Button onClick={action('clicked')}>Hello Button</Button>;
Story1.story = { name: 'with text' };

export const Story2 = () => (
  <Button onClick={action('clicked')}>
    <span role="img" aria-label="so cool">
      😀 😎 👍 💯
    </span>
  </Button>
);
Story2.story = { name: 'with some emoji' };

You could also write both in one file, using a markdown template literal:

markdown template literal

import React from 'react';
import { action } from '@storybook/addon-actions';
import { md } from '@storybook/addon-docs';
import { Button } from '@storybook/react/demo';

const page = md`
# Title

## Subtitle 1

Paragraph 1

<docs-story name="storyA"></docs-story>

## Subtitle

Paragraph 2

<docs-story name="storyB"></docs-story>
`;

export default {
  title: 'Button',
  parameters: {
    component: Button,
    docs: { page }
  },
};

export const Story1 = () => <Button onClick={action('clicked')}>Hello Button</Button>;
Story1.story = { name: 'with text' };

export const Story2 = () => (
  <Button onClick={action('clicked')}>
    <span role="img" aria-label="so cool">
      😀 😎 👍 💯
    </span>
  </Button>
);
Story2.story = { name: 'with some emoji' };

The docs page wouldn’t need to load react in the preview this way, keeping the separation between the manager and the preview clearer.

In a followup step the doc blocks could be exposed as well, thought that will require loading react.

Describe alternatives you’ve considered This could be a separate addon entirely, but I think it’s best to work from one core docs addon and have mdx and md as ways to write docs.

Are you able to assist bring the feature to reality? Yes

[LarsDenBakker]

We will have a first version to show soon 😃

[BPScott]

The metadata at the top - imports and the export default config could be solved with yaml frontmatter, and the story name could be attached as part of the meta of the component block. That would remove the need for any special markdown parsing. You’d need to read front-matter and extract the contents of the fenced code blocks whose meta begins with story: and convert them into a story but that’s you can get all that using graymatter for the frontmatter parsing and remark for reading the md AST.

imports: |
  import {html, withKnobs, withWebComponentsKnobs} from '...';
story: |
  {
    title: 'Decorators/WithWebComponentKnobs',
    decorators: [withKnobs, withWebComponentsKnobs],
    parameters: { component: 'demo-wc-card', options: { selectedPanel: 'storybookjs/knobs/panel' } }
  }
---

# My first story

That is one hell of a preview :+1: 

```js story: Provide own light dom
  <demo-wc-card></demo-wc-card>