In the Docs addon, import description from a Readme file

[aleshh]

Is your feature request related to a problem? Please describe.
The docs addon default functionality is awesome, except that the description field is populated from JSDocs within the component file.

Describe the solution you'd like
An parameter for the docs addon to use a .mdx file for the description that retains all the other default docs functionality.

Describe alternatives you've considered
The readme addon sort of works, but it also adds the readme to the canvas, and adds a mandatory sidebar. Seems maybe I can I do this with a slot function, but I can't find any example code.

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

[atanasster]

@aleshh - you can do that in a couple of ways

1. Compose your default DocsPage anyway you like it (its not that hard):

import { DocsContext, Title, Subtitle, Description, Primary, Props, Stories } from '@storybook/addon-docs/blocks';

addParameters({
  docs: {
    page: props => {
      const context = React.useContext(DocsContext);
      //here use the context to find the file name for the markdown description
      const md = require('./stories/notes/notes.md');
      return (
        <>
          <Title />
          <Subtitle />
          <Description>
            {md.default}
          </Description>  
          <Primary />
          <Props />
          <Stories />
        </>
      );
    },
  },
});

2. Using the slots (a bit easier but might get deprecated soon):

import { DocsPage } from '@storybook/addon-docs/blocks';
addParameters({
  docs: {
    page: () => <DocsPage descriptionSlot={(d, context) => {
      //here use the context to find the file name for the markdown description
      const md = require('./stories/notes/notes.md');
      return md.default;
    }} />,
  },
});

[aleshh]

This is intriguing, but I cannot get it to work. I'd like to apply the same format to all my stories, so I'm doing addParameters in my config.js file and (1) I need a path relative to the story, not the config file, but require can't take a computed path and (2) even when I remove the require and {md.default} the template doesn't return anything.

[atanasster]

@aleshh -

1. you can load the markdown directly in the stories and setup the slot globally, like that:

docs: {
    page: () => (
      <DocsPage
        descriptionSlot={(description, context) => {
          if (context.parameters.description) {
            return context.parameters.description;
          }
          return description;
        }}
      />
    ),
  },

and in the story:

import md from './notes/notes.md';

export default {
  title: '....,
  parameters: {
    description: md,
  },
};

2. Check out on dynamic imports for webpack (https://wanago.io/2018/08/20/webpack-4-course-part-eight-dynamic-imports-with-prefetch-and-preload/)

docs: {
    page: () => (
      <DocsPage
        descriptionSlot={(description, context) => {
          // here use the context to find the file name for the markdown description
          const mdFile = context.parameters.fileName.replace(/^.*[\\\/]/, '');
          try {
            // eslint-disable-next-line import/no-dynamic-require
            return require(`./stories/notes/${mdFile}.md`).default;
          } catch (e) {
            return description; //default description
          }
        }}
      />
    ),
  },

[shilman]

another solution would be to write a custom webpack loader that handles this case. for each component file it would check for the existence of a README in that directory and then annotate the component with the README's contents. Then the slot could read that off the component, much like it currently does for component.__docgenInfo. sounds like a lot of work if you're not familiar with webpack, but could probably be done without too much difficulty. and sounds useful!