docblock comments in *.stories.(tsx|jsx) files

[andyford]

I noticed that the example components in a default install of Storybook (for React) add a docblock style comment inside the component source code which then is displayed in the Docs tab of the related story. Specifically, Button.tsx is annotated like so:

/**
 * Primary UI component for user interaction
 */
export const Button = ({

this docblock annotation then appears in the Docs tab:

... this is fantastic! But I'd like to take it to the next level and have a docblock comment for each individual story in my Button.stories.tsx file (rather than only one comment at the top of the Docs tab). I tried it out but it doesn't seem to work. Is there some way to make this work?

[andyford]

OMG I found it! (paramers.docs.description)
https://storybook.js.org/docs/react/writing-docs/doc-blocks#docspage-2

export const WithStoryDescription = Template.bind({});
WithStoryDescription.parameters = {
  docs: {
    description: {
      story: 'Some story **markdown**',
    },
  },
};

yay!

[andyford]

...but it seems that paramers.docs.description.story won't show up for the FIRST story in a *.stories.tsx file, but it will show up for all the rest of the stories.

Which means, to annotate the first story, you have to add a docblock to the component source code (Button.tsx for example)

am I missing something?

[mploigt]

I had the same problem and found the solution for adding subtitle and description to the first story on a storybook page. In meta add a parameters block like you did for the stories, but change story into component. You can also change the subtitle:

const meta = {
    parameters: {
        docs: {
            componentSubtitle: "This will display a subtitle for the first story",
            description: {
                component:
                    'This is the description for the first story',
            },
        },
    },
    [...]
};

[andyford]

Whoa! I was looking at this again just today. Ever since 2021 I've been doing this:

import {
  ArgsTable,
  Description,
  Primary,
  PRIMARY_STORY,
  Stories,
  Title,
} from '@storybook/addon-docs';

// and in meta...
parameters: {
    docs: {
      page: () => (
        <>
          <Title />
          <Description
            children={
              'blah bla bla'
            }
          />
          <Primary />
          <ArgsTable story={PRIMARY_STORY} />
          <Stories />
        </>
      ),
    },
  },```
  
  I tried SO many different ways to get the description on the page but I never tried your exact approach. Works like a charm (on 6.5.x)
  
Thanks @mploigt!

[chatterbox777]

thank you very much, @mploigt , works for 6.5.10

just replaced

description: {
story:
'This is the description for the first story',
}

        with ->>>  description: {
            component:
                'This is the description for the first story',
        }
        
        and it works! finally!

[JReinhold]

This is actually how it works in Storybook 7 with CSF3, where you can write JSDoc above your story export and it will end up as a description on the story in the docs.

This is documented here: https://storybook.js.org/docs/vue/api/doc-block-description#writing-descriptions