Addon-docs: Decorators for MDX and DocsPage

[patricklafrance]

Is your feature request related to a problem? Please describe.
I would like to be able to add custom widgets at the top of all my MDX pages.

Ideally, I would define those widgets once in some kind of container that would wrap all my MDX pages.

Describe the solution you'd like
It could be achieve by a decorator with the same behavior as the story decorator but for MDX and DocsPage.

addDocsDecorator((page, context) => <DocsContainer page={page} ... />)

Describe alternatives you've considered

• Manually add the widgets in all my MDX pages.
• Support tool addon in MDX pages

[shilman]

I think you can do this already, though with a slightly less flexible mechanism. Let's suppose I want to wrap every docs page with a red border. It should be possible using something like this:

import { addParameters } from '@storybook/client-api';
import { DocsContainer } from '@storybook/addon-docs/blocks';

addParameters({
  docs: {
    container: ({ children, context }) => (
      <DocsContainer context={context}>
        <div style={{border: '5px solid red'}}>
          {children}
        <div>
      </DocsContainer>
    ),
  },
});

[atanasster]

Just for documentation completeness purposes, the following is also an equivalent:

import { DocsPage } from '@storybook/addon-docs/blocks';

addParameters({
    docs: {
      page: props => (
        <div style={{ border: '5px solid red'}}>
          <DocsPage {...props} />
        </div>
      ),
    },
});

[patricklafrance]

Super cool, I will try, thank you!

[shilman]

The difference between the two is that my example will be applied to both DocsPage and MDX pages, whereas @atanasster 's will just be applied to DocsPage pages 😉

[atanasster]

ah, yes - I missed that for .MDX

[patricklafrance]

I tried

import { addParameters } from '@storybook/client-api';
import { DocsContainer } from '@storybook/addon-docs/blocks';

addParameters({
  docs: {
    container: ({ children, context }) => (
      <DocsContainer context={context}>
        <div style={{border: '5px solid red'}}>
          {children}
        <div>
      </DocsContainer>
    ),
  },
});

Since i am using MDX and it doesn't seem to work with beta.9.

[shilman]

@patricklafrance I was wrong. My snippet only works for DocsPage. The MDX compiler hard codes the container:

componentMeta.parameters.docs = {
  container: ({ context, children }) => <DocsContainer context={{...context, mdxStoryNameToId}}>{children}</DocsContainer>,
  page: MDXContent,
};

It needs to be updated to inject the mdxStoryNameToId into the context some other way.

[shilman]

Jeepers creepers!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.3.0-beta.10 containing PR #8968 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.

[amcdnl]

We should add this to the docs.

[shilman]

@amcdnl it's currently documented here: https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#overwriting-docs-container

@jonniebigodes i guess we should get this into the main docs site

[koop]

+1 — I was just searching for how to do exactly this

[pm0u]

How do we do this in storybook v7? The linked doc no longer exists. Attempting to define a container in either the parameters.docs field of preview.ts, defining this in the parameters.docs prop of Meta in the story, nor defining this via addParameters in manager.ts seem to work.

My larger goal is to have some CSS variables defined that are defined in a component that leverages next/head. That doesn't seem to be the issue though, even this doesn't work:

<Meta
  title="Title"
  parameters={{
    docs: {
      container: ({ children, context }) => (
        <DocsContainer context={context}>
          <style
            dangerouslySetInnerHTML={{
              __html: `
              body {
                background-color: red !important;
              }
        `,
            }}
          ></style>
          {children}
        </DocsContainer>
      ),
    },
  }}
/>

[Pegase745]

@pm0u Here's the link to the doc that allows to do this: Customize the docs container
I just tried it under SB7 and it works as expected

[pm0u]

@Pegase745 Thanks - I eventually got this to work.

It seems that my test case was not a good one, as the CSS was there in fact but a lower element has background: white and covers the body entirely 😅

The initial issue I had with pulling in next/head here did persist, so I had to inject anything in the head separately from the means I was using in production. There was a couple of confounding issues here.

[mririgoyen]

All of the options using parameters.docs.container affect both DocsPages and MDX. Utilizing parameters.docs.page only affects DocsPages. How can we target only MDX?

[longzheng]

All of the options using parameters.docs.container affect both DocsPages and MDX. Utilizing parameters.docs.page only affects DocsPages. How can we target only MDX?

I did a super ugly hack for my own use case where I wanted to apply a React theme provider for some theme-based MDX docs. It does a few type casts but it works.

const CustomDocsContainer = (props: any) => {
    const children = props.children as React.ReactElement;

    // check if children is of type MDXContent
    const isMDXContent = (children.type as any).name === `MDXContent`;

    if (isMDXContent) {
        // get theme from globals
        const theme = (props.context.store.userGlobals.globals.theme ||
            `light`) as Theme;

        return (
            <ThemeProvider defaultTheme={theme} key="theme">
                <DocsContainer {...props} />
            </ThemeProvider>
        );
    }

    return <DocsContainer {...props} />;
};


const preview: Preview = {
    parameters: {
        docs: {
            container: CustomDocsContainer,
        },
    },
};

export default preview;