Feature request for greater discoverability in large storybooks

[trevordmiller]

Is your feature request related to a problem? Please describe.

I work for an organization that has hundreds of apps and websites. We have helped migrate many of them to use storybook and will continue to do so going forward. Storybook is fantastic and meets our needs well for the most part. But one area it struggles in is in projects that have many components (some of them hundreds) it is hard to find specific components through folders and titles + searching alone.

Describe the solution you'd like

It would be very helpful to be able to be able to include keywords that pull up specific stories from searching; so keywords that are not in the story title could be included in search.

Describe alternatives you've considered

We've tried to organize stories the best we can using the nested folder structure. This works well for components that only have one function. But many components have multiple functions, so a 1 to 1 ratio of discoverability doesn't work well.

Are you able to assist bring the feature to reality?

Possibly, if I could get a bit of direction from a storybook admin :) But with my current workload, having the storybook team implement would be helpful.

[shilman]

I think tagging would be useful. FYI, Storybook's search also includes the file path (I think?) so this might be a short-term workaround for you.

[LdsDannyStaten]

yes please!

[mackenziemi]

This is an awesome idea! Great improvement for a great product

[plumbblake]

It looks like some work was done on this.
#4139
Did this never actually make it into the final release?
@shilman

[trevordmiller]

Yeah the searchTags property in the issue mentioned by @plumbblake looks like what this issue is requesting. I don't see documentation for it though, was it pulled out of the alpha it was released in? Or was it released and is just undocumented?

[shilman]

https://github.com/storybooks/storybook/blob/11d9a10f33a92d405ce63231beb28f9b46194ee6/lib/ui/src/components/sidebar/treeview/utils.js#L172

Looks like filename and notes are the extra fields. I argued against these actually since it doesn't make sense unless we have a UI to go along with it. I'd be excited to have tags and a tag UI for search results

[trevordmiller]

@shilman So for our use case, of adding more terms for searching, would it be alright for us to use the notes property to add more search terms? Or is this a brittle implementation detail we shouldn't touch? If it is a public facing feature, could it be documented?

[shilman]

@trevordmiller Documentation PRs welcome. If it was up to me it wouldn't be part of the feature in the first place, and we'd have a proper solution like what you're suggesting. But in the rush to ship I didn't spend too much time arguing.

[trevordmiller]

I'm happy to submit a documentation PR. Can you please direct me to where this should be done? And would the following information be correct?

---

Searching

By default, search results will show up based on the file name of your stories. You can extend this with notes to have certain stories show up when the search input contains matches. For example, if you built a "Callout" component that you want to be found by searching for popover or tooltip as well, you could use notes like this:

storiesOf('Callout', module)
  .add(''Simple", () => (
    <Callout>Some children</Callout>
  ),
  .add(''With title", () => (
    <Callout title="Some title">Some children</Callout>
  ),
  {
     notes: "popover tooltip"
  }
)

[shilman]

Thanks @trevordmiller !! That looks great and I appreciate the follow-through.

There isn't a perfect place for this right now. The following two options are your best bet without rearchitecting the docs site:

• Storybook UI README
• Writing stories

You can make the call on what you think works best!

[trevordmiller]

@shilman Ok thanks. Another question: is there a way to add notes for an individual story? Like at the .add level, not only the storiesOf level?

[trevordmiller]

...and how does it related to what is documented here: https://github.com/storybooks/storybook/blob/next/docs/src/pages/basics/writing-stories/index.md#using-markdown

Like what is the type / structure of the notes key? It seems it can either be a string or an object with markdown: string?

[shilman]

@trevordmiller Sorry there's a typo in your example. The third arg of .add is the story parameters. So:

storesOf('Comp', module)
  .add('some story', () => <Comp />, { notes: 'story notes' })
  ...

If you want to add it at the component level:

storiesOf('Comp', module)
  .addParameters({ notes: 'component notes' })
  .add( ... )

And yes, notes can be a string or an object containing a markdown field. Not the best API but it is what it is.