Write documentation: How to use (Angular) components in mdx files

[MickL]

Is your feature request related to a problem? Please describe
The docs are not very clear on how to use/place Angular components inside of a mdx file. IMO the docs are the biggest flaw of Storybook at the moment and took me hours and hours and a lot of frustration already. I often end up figuring things out by accident.

The mdx documentation is even for React, not Angular? https://storybook.js.org/docs/angular/writing-docs/mdx
On the other hand (randomly again!) I found that here is a Angular documentation: https://github.com/storybookjs/storybook/tree/master/addons/docs/angular But why is that not part of the actual Angular docs?

I would like to have a Story that is generated by a mdx file that contains multiple components, e.g. here I have 3 components:

<h1>Buttons</h1>

<app-button>
  Hello world <app-icon icon="magic-hat"></app-icon>
</app-button>

<app-badge title="I am a badge component"></app-badge>

That is not really documented. First I tried to put in just one component:

<Meta title="Pages/" component={ButtonComponent} />

<app-badge title="I am a badge"></app-badge>

or is it?

<Meta title="Pages/" component={ButtonComponent} />

<BadgeComponent title="I am a badge" />

If I guess the documentation right it is the second approach but my component also depends on other services / a shared module. If I read the docs right importing it can be done like in ts files:

<Meta title="Pages/" component={ButtonComponent} decorators={[moduleMetadata({imports: [BrowserAnimationsModule, SharedModule]})]}/>

But then I get:

Promise rejection: Class constructor IconComponent cannot be invoked without 'new' ; Zone: ; Task: Promise.then ; Value: TypeError: Class constructor IconComponent cannot be invoked without 'new'

Found randomly this documentation that shows something like this for Angular:

<Story name="Storyname">
  {{
    component: BadgeComponent,
    props: {
      title: "I am a badge"
    },
  }}
</Story>

But I dont want a story I just want to place components inside a mdx file. Btw I wonder why the inputs are called props. If I would have never worked with React I would never know that this are the inputs.

If I could get past placing a component in a mdx file my next question would be how to add multiple components as this seems to be no array:

<Meta title="Pages/" component={ButtonComponent} />

Additional context
Other things I struggled with with the documentation:

• <Canvas> is not documented but I was looking exactly for that: Story without a component / just html #13783
• Options that a Canvas has, like isColumn, columns are not documented but I was looking exactly for that
• MDX files lets one write JSX but JSX is not familiar to anyone not using React. In fact there are a lot of super annoying things like you cant have unclosed tags <img src=""> or you cant use some attributes <div class="">. This things should be pointed out when speaking about MDX files, just a sentence like "Watch out: JSX files have some characteristics, find out more about JSX -here-"
• MDX docs have a React example not Angular?

[shilman]

Thanks for your documentation feedback. cc @jonniebigodes @ThibaudAV @kroeder

I don't know the history behind calling the inputs props. @storybook/angular was developed by angular users so I always figured that props was also an angular thing. If it's not, we should consider deprecating props in favor of something more Angular-ish in a future version. Open to suggestions.

It's not enough, but there are some basic Angular MDX examples here:

• https://raw.githubusercontent.com/storybookjs/storybook/next/examples/angular-cli/src/stories/addons/docs/simple.stories.mdx
• https://raw.githubusercontent.com/storybookjs/storybook/next/examples/angular-cli/src/stories/addons/docs/addon-docs.stories.mdx

As for the documentation, Storybook is a large project and we're still filling in snippets for different frameworks/scenarios. If you can help improve the documentation via PRs, this would help future users avoid the frustrations you just faced. Storybook is a community-driven project and we rely on our users to help us get good coverage over the various frameworks and scenarios it supports.

[aitorllj93]

I don't think it's possible to just "add a component inside of a mdx file" 🤔

The mdx is not "inside" an angular application. But generate component with angular-element or iframe to display some angular component. And to do this you need to use react Story component.

the mdx file of the docs addon is react app the only component, i think is possible do place directly is react component (not sure)

I think the feature you are looking for does not exist only add an angular component in the mdx without Story. I'm not a docs expert maybe I'm wrong

What about a new Angular Story component (or maybe Element)

[aitorllj93]

I don't think it's possible to just "add a component inside of a mdx file" 🤔

The mdx is not "inside" an angular application. But generate component with angular-element or iframe to display some angular component. And to do this you need to use react Story component.

the mdx file of the docs addon is react app the only component, i think is possible do place directly is react component (not sure)

I think the feature you are looking for does not exist only add an angular component in the mdx without Story. I'm not a docs expert maybe I'm wrong

Anyway, I think in most of the cases what we need is to be able to load React components inside the Angular framework as we do with web components. In that way, we can safely migrate the components layer to React and stories to mdx

[EswarSk]

@shilman is this still a limitation of addon-docs? Was there any update with MDX2? Can you please share any workaround? In angular for a typography component, having to create stories for each variant and then using them in the MDX2 file for documentation is a very tedious task.

[shilman]

Yes. In Storybook 7 we separated story definition from MDX docs. You can read about it here, esp the part about referring to stories by reference and not by ID

https://storybook.js.org/blog/storybook-7-docs/

[EswarSk]

Okay, I can use something like this
<Story of={ButtonStories.Primary} /> to render the Primary story in the MDX file. But this still requires me to create all the stories for the button component. (Example ButtonStories.Default, ButtonStories.Secondary and so on ). The same scenario in a react application is much simpler. I can just use <Button type= 'primary' /> and the primary button component is rendered (without the need to create a story). Is this still not possible in storybook for angular?

[ThibaudAV]

Btw I wonder why the inputs are called props. If I would have never worked with React I would never know that this are the inputs.

I am also wondering about this. I find that it is not clear 'props' from an angular point of view.
If you have any suggestions? a feedback? Maybe with the next major of storybook it would be possible to improve this point. 🤷‍♂️

The default of props that seems to me the most disturbing is that it overrides the properties of an angular component even if they are not "Input/Output".

[aitorllj93]

That's actually the behavior of the component as it's object-oriented instead of functional. Nothing to do on that, for me, props is a good naming

[MickL]

The word prop/props is not part of the Angular world at all.

[zecka]

Anyone find a way to display an angular component in mdx file without creating a story ?