Addon-docs: DocsPage "slots"

[shilman]

Problem

Current version of DocsPage tries to do a bunch of stuff automatically for you based on existing addon-notes/addon-info/docgen annotations. This can result in weird behavior depending on how you set up your storybook.

Solution

1. Define a set of "slots" on the page and parameters to fill them.
2. Users can fill those slots manually
3. Some of those slots may be filled automatically or we may offer ways to configure them to be filled by existing info.

The idea is that we give you a minimal experience out of the box that looks good, and then we help you get to a great page with as little extra work as possible.

[domyen]

👍 Seems like the right balance of "It Just Works", customizability, and maintenance burden.

[leerob]

Would definitely like to see some documentation examples of how you can add blocks in your own MDX. For example, I was messing with this.

import {Button} from '@storybook/react/demo';
import {Story, Meta, Props} from '@storybook/addon-docs/blocks';

<Meta title="MDX|Button" component={Button} />

# Hello Docs

Welcome to the future of Storybook!


<Story name="hello">
    <Button>Hello button!</Button>
</Story>

<Props of={Button} />

It'd also be cool to expose a way to have color formatted code like the story previews. Or can you use Preview to do that? Use case would be including the import statement as well. Here's our existing story using storybook-readme.

And was able to get close messing around with the preview (p.s. loving the props table!)

Notice the font is wrong in the preview though, thinking that relates to #7264.

[shilman]

@leerob Thanks! I think your questions are more about MDX than about DocsPage.

To clarify:

• DocsPage is a prebuilt component that you can add to all your stories to generate reasonable documentation with a single line of code.
• MDX is a much more flexible authoring format that can be used to create any page you want with a mix of markdown and JSX.

5.2 will introduce and document DocsPage and best practices for turning existing Storybooks into rich documentation sites. 5.2 will support MDX, but we won't be emphasizing it as part of the release.

In 5.3 we will refine and document MDX and come up with best practices for that, and that will be the "docs" focus of the release.

RE: highlighting code blocks #7162. You'll just use regular GFM code blocks and docs will do the rest for you. It's an easy feature actually but I'm just hustling to get the 5.2 release out the door so I haven't gotten around to it. In the meantime you can use the Code block, which is used by Preview.

RE: including your own components in MDX, just import them! As for DocsPage, let's see how this feature shakes out. 😄

[shilman]

Hurrah!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.2.0-beta.24 containing PR #7680 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

Closing this issue. Please re-open if you think there's still more to do.

[stephtr]

Should mdx files be automatically decorated by DocsPage?
If I export stories, DocsPage gets automatically created, but not for mdx, even if I add addParameters({ docs: DocsPage }); to my configuration (which shouldn't even be necessary any more). Or do I have to wait for that until 5.3?

[shilman]

MDX is an alternative to DocsPage. DocsPage takes all your stories and turns them into documentation. MDX takes your documentation and turns it into stories (roughly). If you're writing MDX containing <Story name="...">...</Story> stories and it's not showing up in your storybook, perhaps you're not loading the MDX files in your .storybook/config.js? Feel free to jump on our Discord and I can try to help sort things out.

[stephtr]

Ah ok, thanks. For me everything is working as intended. I just had the feeling that there would be a way to automatically generate DocsPages out of mdx, such that the the following two snippets end up being displayed in the same way (including the addition of headings and props table):

<Meta title='Button' component={Button} />

<Story name="Test">
	<Button />
</Story>

export default {
	title: 'Button',
	component: Button,
};

export const Test = () => <Button />;

[shilman]

Great Caesar's ghost!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.2.0-beta.29 containing PR #7741 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.